3 ms·
I've never seen a documentation effort fail for the choice of content authoring platform. Efforts fail because: - project leaders do not prioritize it - proj
by hughes 7y ago
I've never seen a documentation effort fail for the choice of content authoring platform.
Efforts fail because:
- project leaders do not prioritize it
- project implementers are unwilling to write it
- documentation authors are unable to clearly communicate the important information
If the choice of markup becomes the limiting factor, existing documentation can always be transformed (either by machine or manual effort). But missing documentation always seems to come down to one of these three items.
- dharmab 7y agoI've seen documentation efforts fail because of Confluence's terrible search.
- time0ut 7y agoI've given up trying to use Confluence. Our internal instance is a wasteland of smoldering ruins. It is such a hideously bad tool on so many levels, including a "search" feature that will fail you even if you search by exact title.
- folmar 7y agoSearch is easy - just export whole space and you get big but quite reasonable HTML file which then can be searched with ^F.
- time0ut 7y agoHeh. I have done this...
- Tomte 7y agoJust to +1 that, it's my experience, as well. Exact search for the page title does not find the page. How can that be? I mean, isn't that the simplest possible search? And as far as I understand it, Confluence search is powered by Lucene, a world-class library for natural text search. How could Atlassian make it perform that bad? Is there any explanation beyond "they are idiots", because they are probably not.
- time0ut 7y agoFull text search on fairly arbitrary content that will perform well and return high quality results is a pretty hard problem. It is largely a solved problem now, but it takes more work than just throwing everything into a Lucene index. That said, it is clear Atlassian just sucks at search and doesn't really seem to care. Search in JIRA is even worse if you can imagine that. BitBucket is ok, but a different sort of use case. I think they could make their search great if they wanted to, but why bother when the people purchasing the product probably won't even use the product enough to notice?
- kakwa_ 7y agoWell, to quote Jordan Sissel (author of Logstash) "Wiki means: where documentation goes to die". I found maintaining a good documentation inside a wiki tough. People (including me) will tend to create new pages willy nilly, never deleting old ones. The layout is generally rough, you generally have a basic structure, but under that, you see a mess of pages at every levels. The information is often out of date and often redudant which creates noise even if you have quality pages (and even if you have a good search). The plus side of a wiki is its accessibility. Committing a text file inside a git repository is a tough ask to none technical people. Asking them to "fork" and do a pull request is even harder. But to maintain quality documentation inside a wiki, a dedicated curator is almost always needed. It's also not in or near the logical path of code/product changes. You need to login into a dedicated system, find the page you need to change or where to add a new page and finally do the edit. It's kind of hard to have a systematic good documentation in such circumstances. Also, doing reviews and documentation versioning (in sync with product versions) is kind of hard with a wiki. For all these reasons, I tend to prefer putting my documentation right next to my code in a markup language (simple Markdown README.md for simple projects, RST+read the doc for more complex ones, but that's a personal preference). You have far more incentive to edit the documentation, versioning is automatic, documentation versions are in sync with your product versions, review is easier (just include it inside the PR, same as code review). The downside is less outside accessibility. It's also a very "low altitude" documentation, great for documenting individual libraries or components, it's not so great for things like documenting overall system architecture, or organizational stuff like processes, basically anything not tied to one specific component. In the end, wikis have their role, but I found they are generally overused and miss-managed.
- with-point 7y agoI've also had enough with various wikis. And at some point we didn't find a decent tool for documenting our projects. We decided to build our own tool https://nots.io https://nots.io (yay NIH syndrome). The main idea is to make possible to link any type of doc like plain or markdown text, files, google docs right with the code. To give all docs a clear scope. And make it easy to discover what code is documented from the site or IDE. We also track the relevance of each added document. When new commits come in and the code behind the doc changes, we decrease its relevance factor (we call it the fresh rate), and let you know if the document is obsolete now. We have a demo (https://nots.io/demo https://nots.io/demo). Check it out, I'd love to get feedback.
- einpoklum 7y agoI have. If the "content authoring platform" is not integral to where the source code / original content is written - many people, or I should say most people, tend to just not write it. And then it only gets written with very strict disciplined pre-commit reviews.
- hughes 7y agoSounds to me like an example where project implementers are unwilling to write it, not that the platform prevented them from doing so.
- tatersolid 7y ago> I've never seen a documentation effort fail for the choice of content authoring platform. I also have, multiple times in a 24-year career. The XML-based monstrosities sold as “enterprise content management” have been bought by many a non-technical manager but never produced useful output once.