I don't get the author's dislike of Confluence, when it is just a different representation of.a Wiki. I actually like the way Confluence implements draw.io so I can quickly scribble an architecture or A flow.
What am I missing here?
The tree-based approach to organizing documentation sucks
71–80 of 97 posts
Re: The tree-based approach to organizing documentation sucks
#72Earlier quoted context omitted.
I had the same problem and tried a bunch of stuff (mediawiki, confluence, GitHub wiki, gitlab wiki, shared drive, Wordpress, SharePoint) and currently just use GitLab pages because the fork/merge flow for markdown was easier than trying to grant access and moderate a wiki. It’s still easy to solicit edits, but the issue/question flow is helpful, and have some review process seems to help. Lots of people struggle with…
Conjecture: almost every belief that your wiki needs support for ACLs and needs to be moderated (for any reason other than spam) is a belief that's wrong from the start. (And it should be a criminal offense the way that GitHub and GitLab to have corrupted the word "wiki" to be understood to include PR- and review-based workflows centered around big collections of offline source files—the very practice that the wiki w…
GitHub and GitLab have a wiki feature that is a sort of crappy wiki with no merge requests.
The problem is that wikis can’t be globally editable without license events so in order to edit the wiki you need permissions on the project.
The PR flow is for the non-wiki where there’s just files in a repo that only active project users can edit but anyone can fork and PR.
So it’s a lot easier administratively than trying to grant everyone edit permissions on a repo just to edit a wiki.
If there was a decent wiki product I would love to run it and just have every staff member with edit permissions. But that’s the dilemma.
Re: The tree-based approach to organizing documentation sucks
#73Users like outline trees. Trees communicate a lot more information about what the project does and what systems or features support what. Wiki linking, in that case, is just an alternative way to duplicate the content of a page on the tree. Other methods include redirects and using software that can symlink individual blocks of text to keep them in sync. As to why documentation is bad, it's because people close to a…
> using software that can symlink individual blocks of text to keep them in sync.
I've usually seen those called transclusions. Occasionally someone reinvents the idea and comes up with some other neologism, often based on the word 'quote' (eg. superquote, hyperquote, etc.).
Re: The tree-based approach to organizing documentation sucks
#74This was solved in 1995 with WikiWikiWeb. Not sure why the bi directional links did not become more of a standard.
Bi-directional links basically leads to linkspam of various sorts. Aside from actual spam, you get the pages that are popular link targets having ginormous lists of backlinks to too many other pages in the wiki (which makes the backlink list useless).
Better to have specialized templates and page types to expose the right amount of context (eg. Wikipedia category pages, navboxes, sidebars, etc.).
Re: The tree-based approach to organizing documentation sucks
#75I haven't found a good enterprise (for SME's) wiki. Mediawiki is not really usable out of the box without significant work. Obvious stuff is hard to set up, e.g. private wiki with SSO.
> I haven't found a good enterprise (for SME's) wiki. Mediawiki is not really usable out of the box without significant work.
Hmm. Have you tried any of the Mediawiki enterprise distributions?
Re: The tree-based approach to organizing documentation sucks
#76Scrapbox, an opinionated wiki service, againsts directory structure that can't scale. It's based on hypertext. Try it out. https://scrapbox.io/
Re: The tree-based approach to organizing documentation sucks
#77I found organizing and finding documentation to be a huge problem ten years ago, not so much now with wikis having decent search. The biggest problem remaining is that it's simply hard to write good documentation, much harder than providing ad-hoc help in person or over Slack. The reason is that every time you provide an ad-hoc explanation of how something works, you have a concrete context: a person, what they're tr…
[deleted]
Re: The tree-based approach to organizing documentation sucks
#78I think of documentation as my little secret superpower. It makes one more productive (i.e. one doesn't need to keep getting interrupted to be asked the same question yet again), it makes others more productive (they can unblock themselves and use the docs to supplement their little corner of tribal knowledge), and good docs allows one to offload knowledge of specifics from one's brain such that just searching for a…
What's your superpower to write documentation that helps others? Too often I find I'm writing docs for myself and they confuse users.
Do you have a set of questions you ask yourself when writing, to check it will be useful and usable by users?
Re: The tree-based approach to organizing documentation sucks
#79> The issue is that the documentation tools that so many companies have standardized on are absolutely garbage for actually writing documentation.
No. The issue is that many companies still haven’t realized that you need to dedicate people to this job, that is, technical writers, documentarians, information architects, etc. Blaming the tools is like blaming a car without a driver for not moving.
To "people over process" add a new mantra to your agile way of work: "people over tools".
Re: The tree-based approach to organizing documentation sucks
#80I think the author is missing a key part of why developers often don't like writing documentation but do like answering questions: replacement value. A developer's compensation is based upon their perceived value (how much it seems like they are needed) and replacement value (how much would it cost to replace them). A developer that answers questions gets a reputation for helpfulness - this increases their perceived…
Fair point, but I really doubt that is really a key component, specially given how fruitfull the developer market is. Very few people stays in the same company for more than 3-4 years in my experience. So, if you're just going to stay a couple years, you probably don't care about your replacement value.
I'd say that, in general, people don't like writing docs or answering to people. But if someone asks you a question, it'd be very hard to decline to answer, whereas writing documentation takes effort and initiative (and it won't prevent people from asking things, because most people don't like reading docs). Unless there's someone pressing for people to do it, they simply won't. Both because they don't care about doing it and also because the activity is not valued anyway (ask any project owner if they'd rather have great documentation or one more feature).
Also, the value of documentation is questionable in the simple software using standard components as most of us do. I'd be interested in seeing a study to know whether good software docs really improve productivity or reduce the number of bugs.