Ask Slashdot: What Are Some Tips For Creating Effective Documentation? 108
theodp writes: "My advice to all the young tech enthusiasts, future engineering managers, and CTOs is simple," writes Vadim Kravcenko in The Surprising Power of Documentation. "Cultivate a love for documentation. You may view it as a chore, an afterthought, or a nuisance. But trust me when I say this: Documentation isn't just a task on your to-do list; it's a pillar for success and a bridge that connects ideas, people, and vision. Treat it not as a burden but as an opportunity to learn, share, and create an impact."
So, what would Goldilocks make of your organization's documentation -- Too much? Too little? Just right? Got any recommended tools and management tips for creating useful and sustainable documentation?
So, what would Goldilocks make of your organization's documentation -- Too much? Too little? Just right? Got any recommended tools and management tips for creating useful and sustainable documentation?
Documentation is king (Score:5, Insightful)
Without documentation pretty much everything would grind to a halt. That's not hyperbole.
People dump on documentation, but it's how you learn 99% of how things work, and how to make them work.
Try doing anything in AWS or Python or Rust or medicine or construction or etc etc etc without documentation, let me know how far you get.
"Ha ha, I can do it all from memory, I have experience!"
Sure you can, now.
But where did those memories and experience initially come from? What were they based on? From the documentation.
Face it, without documentation none of us would be programmers, architects, doctors, lawyers, engineers, surgeons, electrician, bankers, farmers*, professors, nutritionists, etc etc etc etc.
Almost everything we do starts with learning how to do it, and 99% of that comes from...the documentation.
------
*Ever see the manual for a combine or tractor? Hundreds and hundreds of pages. How about a managed switch? The manual for the SG2218 managed switch from TP-Link is 1100 pages long. Good luck figuring that shit out without the manual.
Re:Documentation is king (Score:5, Interesting)
I get a real sense of satisfaction from well-formatted documentation; It's a core component in every project.
I like using a wiki because I can use simple markdown and easily link to related articles.
I often refer back to my own documentation for things that I did years ago and have long since forgotten the details of.
Re:Documentation is king (Score:5, Insightful)
At a prior gig, I introduced the IT manager to a wiki. It was free software which ran on a Windows server (they were an MS shop). At first, he didn't see the value in it. I started putting stuff in there. He'd come ask me something. Have you checked the wiki? Uhh
Fast forward a few months. We hired some more IT folks. We quickly discovered what was poorly- and well-organized. It became a rite of passage for new folks to hit the wiki to find stuff and, if something wasn't there, someone with more experience would help them write it up. New folks quickly came to see the value in it and contribute to it. Stuff got doc'ed, widely, and well-used.
Fast forward a few years. I'm at a new gig. I'm trying to learn my way around the infrastructure and the coding standards. Oh, go ask so-and-so about that. Are there no docs? Nah, just go ask that super-busy person who is juggling the jobs of three people.
We had a wiki (mediawiki, no less) but it wasn't getting used. I used it. I wrote stuff up. More new hires, interns, etc. They're being told "oh, check his wiki page; he's got a ton of stuff linked from there." They start doing the same. It's become a running joke. Can anyone tell me how to do such-and-such? Yeah, I have a page about that; try not to act surprised. After about a month, they're not surprised; they're laughing along with everyone else.
If only one person in the organization knows how to do that task, that task has Bus Factor = 1 (only one person needs to get hit by a bus, or otherwise rendered unavailable, before your organization suffers). A good wiki, where it's easy to write clear docs, and search them 'cuz plain text, can quickly take any task to Bus Factor = infinite. If you want your organization to thrive, you need the Bus Factor as high as possible on everything.
Anytime I have to wrestle with how to do something, I doc it on the wiki. If I need to do it again, next week, I might remember how to do it. After a couple months, it's good thing I doc'ed it. Eagleson's Law says that any code you wrote, but haven't touched for at least 6 months, might as well be written by someone else. It's been flushed from your short-term memory. If you have a mortgage and car payments, cut that number in half. If you have a significant other, cut it in half. For each kid, cut it in half. Pretty soon, you're lucky if you can keep stuff in short-term memory for a week at a time. Spending 5 minutes putting it on a wiki page, which you can find when you need it, will save you a lot of "wrestling."
Re: (Score:2)
Wouldn't the bulk of this information be somewhat protected? Services, server names, ip addresses, aplication or database credentials, key files that are modified etc. I've thought of the wiki idea but without a way to protect the inforamtion it seemed irresponsble ot leave it open to the network.
Re: (Score:3)
Wouldn't the bulk of this information be somewhat protected? Services, server names, ip addresses, aplication or database credentials, key files that are modified etc. I've thought of the wiki idea but without a way to protect the inforamtion it seemed irresponsble ot leave it open to the network.
Confidential information shouldn't be in the documentation, the location of the vault with that information should be in the documentation. (possibly with instructions of how to get the information out of the vault and what the model is for who should have access to the vault keys
Re: (Score:2)
At a prior gig, I introduced the IT manager to a wiki. It was free software which ran on a Windows server (they were an MS shop). At first, he didn't see the value in it. I started putting stuff in there. He'd come ask me something. Have you checked the wiki? Uhh ... oh ... yeah ... there's that info. He quickly saw the value in it and started using it as well.
I couldn't have provided a better example. Documentation is the physical embodiment of knowledge.
Imagine if Edison or Alexander Graham Bell or Henry Ford or Charles Babbage or Grace Hopper had never written anything down? How many times would we be reinventing how to make a light bulb or a carbon microphone?
Re: (Score:2)
Re: (Score:2)
I often refer back to my own documentation for things that I did years ago and have long since forgotten the details of.
Bingo. This guy gets it. He understands that documentation serves as a "time-binding mechanism" so everything doesn't have to be learned and relearned and discovered over and over again.
In a very real way it's what separates us from the animals, who have no way of recording the past so it can be referenced in the future (which often turns out to be 'today').
As I mentioned in another comment, "The palest ink is better than the strongest memory." - Chinese proverb
And this is as true in code people write for
Re:Documentation is king (Score:4, Interesting)
Documentation is like sex. Even when its disappointing, it's still better than nothing.
So that being said, document everything. Don't try to be perfect about it - just document. Preferably in a format that allows cross referencing so you won't write the same bit of text twice. Nothing's worse than having 10 different ways to do something and not being sure what's the correct way. If you only have one way, and it's wrong, at least then it can be documented as wrong and someone needs to fix it, not try to find the 9 other ways you sprinkled in the text.
Document with examples - if you have a parameter that's a bit odd, pull examples from the code to show how it was used (with code references so the source can be looked up).
Even if you can't write detailed documentation, just plopping the prototype on a document plus examples in code where you call that function is helpful - I mean, at least I can try to figure out the function from how you actually use it, and if there's a bug in the code, I can see you never tried triggering it.
Re: (Score:3)
Documentation is like sex. Even when its disappointing, it's still better than nothing.
So that being said, document everything. Don't try to be perfect about it - just document. Preferably in a format that allows cross referencing so you won't write the same bit of text twice. Nothing's worse than having 10 different ways to do something and not being sure what's the correct way. If you only have one way, and it's wrong, at least then it can be documented as wrong and someone needs to fix it, not try to find the 9 other ways you sprinkled in the text.
Document with examples - if you have a parameter that's a bit odd, pull examples from the code to show how it was used (with code references so the source can be looked up).
Even if you can't write detailed documentation, just plopping the prototype on a document plus examples in code where you call that function is helpful - I mean, at least I can try to figure out the function from how you actually use it, and if there's a bug in the code, I can see you never tried triggering it.
I'm not sure I agree.
Generally, the first thing I do when editing a php.ini file is strip out all the comments. Generally, all of the comments are duplicated in the sample file and are providing no value, but make it hard to find the actual config entries buried in all of the comments. A 20 line config file without comments can be easier to read than a 2,000 line config file that has 1,980 lines of comments and 20 lines of code.
Re: (Score:2)
Or be sane and use snippits of INI files that only fiddle with one part of the config and then source them all (much like Debian does with Apache, Nginx, etc. configurations, including PHP stuff)
Re: (Score:2)
So that being said, document everything. Don't try to be perfect about it - just document. Preferably in a format that allows cross referencing so you won't write the same bit of text twice.
This guy gets it. Listen to what he says. Even poor documentation is better than none (usually).
Document with examples - if you have a parameter that's a bit odd, pull examples from the code to show how it was used (with code references so the source can be looked up).
Exactly. Again, tlhIngan understands what I was trying to say.
Documentation is the root of just about everything in one way or another. I know a lot of people will deny this and argue and gnash their teeth rather than admit it, but it's true, and he gets the importance of documentation. Almost everything that gets done in any non-trivial way uses and starts with documentation.
Yes, there are skills that are just "
Re: (Score:2)
Documentation is like sex.
SMH. Only on Slashdot
Re: (Score:2)
Re: (Score:3)
Without documentation pretty much everything would grind to a halt. That's not hyperbole.
Of course that is hyperbole. My experience is that most software teams do not create good documentation, yet their teams still release software. Things are not grinding to a halt. It causes pain, sure, but your extreme statement is still clearly hyperbole.
Try doing anything in AWS or Python or Rust or medicine or construction or etc etc etc without documentation, let me know how far you get.
In my masters program I did work on FDA verification of medical devices, which was focused on using information retrieval to compensate for poor documentation of the software. At least 15 years ago it was still quite common for software written for medical
Re: (Score:2)
My experience is that most software teams do not create good documentation, yet their teams still release software.
And how did they learn to write software? From documentation.
In my masters program I did work on FDA verification of medical devices,
Well we all know that medical devices don't have any documentation, and I'm sure you never used any in that job, right?
While a small portion of my knowledge came from initial reading of documentation
Thank you for admitting that your base knowledge came from documentation. And I bet you and millions of software devs never ever look up functions or anything else in a book or reference, because that would be documentation.
Dang- you were so close to understanding that pretty much everything starts with documentation.
Re: Documentation is king (Score:2)
Re: (Score:2)
Sadly, one of the defense tactics against redundancy used to be avoiding documentation!
Yes, it's also a defense against staying in business. lol
Now most companies are obsessively document-centric, especially since audits became a serious thing.
Also, ever since the day ISO9000 reared its head, shit really went bonkers. Everything had to be documented in excruciating detail. Stuff like "How To Empty The Wastebasket" filled up corporate hard drives just so if an auditor ever asked you how to do it, you could point him or her to a document outlining exactly how to do it. I'd bet there are pages w
consistent location, easy to update, MCWEs (Score:3)
Not a fan of writing documentation, but I hate not having it more....
Documentation should be in a consistent location when possible.
Documentation should be kept in a manner that is easy to update and keep current as things change.
Documentation should include minimal but complete working examples when possible
Almost any documentation is better than no documentation, though extremely out of date and inaccurate documentation can be worse than no documentation.
One and two kinda fight against each other - documenting a process, etc. could be on a sharepoint or whatever but then there will be related javadoc (or similar) comments in the code. A shared service/library may have documentation in the code, a readme at the top level of the repository or its subdirectory in the repo, and maybe on the sharepoint site as well.
Re: (Score:2)
Documentation should try to avoid poor English and phrases that are likely to become obsolete quickly.
For example, the question here uses the form "what are some..." This form was created to get around Stack Overflow rules that prevent questions being asked like a normal person, and it's spread. It will die off as Stack Exchange does, and should be avoided in documentation meant to last.
Re: (Score:2)
It takes great skills to write documentation, but having a good tool helps. Microsoft Word is very bad when it comes to writing documentation that has to have a good version management.
I have encountered a tool named Systemweaver [systemweaver.com] while working in the vehicle industry but it would work well for just about any kind of documentation.
Quality not quantity... (Score:3, Informative)
Go for usefulness over volume. One sequence diagram and some notes might convey much more than ten pages of prose (and more likely to be kept up to date. The code is the best source of what the code actually does so complement it; don't repeat it.
Store documentation with code and/or link to it. Your successor might find the code in the repo but does that point to or contain the documentation? If it's not obvious, they'll probably not look for it. Have some "where to find everything" notes.
Review things periodically. Yes, you'll always update documentation with significant code changes, obviously. But documentation goes out of date in many ways. Avoid the we're-too-scared-to-delete documentation just in case problem. Conversely, some documentation might be temporary, make it obvious this is so.
Re:Quality not quantity... (Score:4, Interesting)
100% consider who your target reader is, and what they probably know, understand, and/or could lookup. Unless they can understand your docs, you have failed, even if you understand it. It can't have jargon, and you must presume English is a second language and so jargon and sayings will be lost on the reader, who doesn't have your background/context.
Many links that explain concepts helps the reader. Being very explicit counts towards being understood. It might sound dry to an American, but to someone who's not American it will be understood. The ore that understand, the more successful you are.
Using a Wiki format is familiar to many, as is gitdocs and other documentation platforms that behave similarly. Having translators is very helpful, as well as someone not-you that can attempt to follow your docs as a proofreader. Presuming that you're writing for a newbie is also a good philosophy. You were a newbie once, too. We all are.
Re: (Score:2)
One sequence diagram and some notes might convey much more than ten pages of prose (and more likely to be kept up to date.
I actually disagree with this. While diagrams can be helpful and quick to understand, they are a nightmare to keep updated. Either the software that was used is a personal license, or a corporate one that has expired, or that not everyone has access to. Or not everybody knows how to use the app and doesn't have time to spend learning when they just want to add a box and move some arrows around.
I have a deep hatred of Lucid Charts for this reason. It became the go-to software for most documentation in my
Re: (Score:1)
About diagram software:
I used to hate making diagrams in Visio (and similar programs). "Ohh, you want to add this class / method / process to the diagram in a logical position? Have fun rearranging the whole canvas!"
Then, someone pointed me towards https://plantuml.com/ [plantuml.com] Just describe in text whatever type of diagram you need, and the lay-out engine renders it for you. The small (human- readable) files can be added to the project's source control if you want version history.
Re: (Score:2)
Hey, that's pretty great! Thanks for sharing.
Automate as much as possible... (Score:1)
write for your audience (Score:3)
Think about who is going to read it and why. Don't just barf a bunch of facts and knowledge onto the page.
Re: (Score:2)
Great point, but on the other hand if due to time constraints or writing abilities all you can do is just barf out an unorganized tangle of facts that is for sure better then just having zero documentation. More people can take that tangle of facts and either get something from it, or absorb it, ask you a few questions, and write reshape it into an "overview", then a bulleted list of steps, and kick
Re: (Score:3)
Yes if there is someone to ask questions of. I've come across times when I've had to pick up unmaintained code after someone vanished (for whatever reason), and in a few cases reading the 'unorganized tangle of facts' actually set me back from where I would have been if I'd just tried to glean meaning from the code.
Re: (Score:2)
Fair enough. I tend to find it helpful sometimes when it says things like "the frobniz and bar combine to...", but far less so when it says things like "destinationFolder is the folder to put items into..." or repeats anything the type system already tells me. Sometimes it is clear a comment/documentaiton was once true but has drifted into a lie (for example documenting on a color/tintColor parameter when the method no longer takes one!), and it is a setback if it is not-obvious that it was once true but
Re: (Score:3)
I have to take exception to that.
I have wasted days due to incorrect documentation that was worse than useless as I would have started with the code and not the documentation if the documentation had not existed.
Donald Knuth has advocated for self documenting code for over thirty years and programs where that is enforced and have minimal comments tend to be much easier to work on and fairly quick to come up to speed on.
The problem with self documenting code is that some people view it as an excuse to put en
Re: (Score:2)
Ok, I agree one should strive to write readable code, but there is a difference between code that uses good argument, method, and variable names and one that ALSO describes any relationships, nuances, and history: let realInch: CGFloat = 96 is ok, but:
// A point is 72 DPI, and CSS 'pixels' are 96 DPI; realInch should match this. "inch" is what most
// of the app should use for mesurment so we can make 'scale models'. However things like fire
// suppression gaps, and notches that match the physical thick
Re: (Score:2)
Think about who is going to read it and why. Don't just barf a bunch of facts and knowledge onto the page.
Exactly, 1000%.
1) Know your audience, and write for that audience, first and foremost.
2) Make it lucid and understandable above all, otherwise it's of no use at all.
3) Understand what your target audience needs to do, then write a path for them to follow.
Good documentation, much like a good program, should be like a hole bored through solid rock. In other words, there should be no way for the user/reader to make a wrong turn.
I Write A Lot Of Docs (Score:3)
I guess my main goal was to not be the go to guy to for answers. No 2am pages into an incident because I'm the only one that knows how it works.
I wrote a doc about the task, check the wiki. If it's not clear, let me know and I'll clarify it or you make the updates.
It wasn't perfect but the nice thing about the wiki and now Confluence, is someone else can update the doc to make it clearer.
And I found that when I wrote a doc, I'd want it to be accurate so I'd dig in, provide reference links to show where I got the answers, clean it up to be clear to my coworkers.
Heck, even for my home project right now I've created a bunch of docs in part because the docs I'm finding on line assume you don't have a production type environment for a homelab.
http://carl.schelin.org/?p=191... [schelin.org]
[John]
Re: (Score:2)
The best tool so far for organizing my Docs and to-do stuff. They charge money for the collaborative features.
Experience counts (Score:1)
The importance of WRITING good tech documentation can only be appreciated after you’ve had to READ documentation to get your job done under pressure. Train your young engineers by making them suffer through development of a few simple test systems by giving them only tech docs - no reviews.
Re: Experience counts (Score:2)
100% agree that experience matters most. Read lots and lots of documentation. Read the owners manual for your home appliance and automobiles. Read computer service manuals, software installation and maintenance guides. Read API listings with usage details and CLI guides for computer hardware appliances.
As you read those, you'll find the parts you like and the parts you hate. Copy the parts you like, then practice writing docs as much as you can.
Later, go back and try to follow what you wrote, coming in
Hire a tech writer (Score:1)
1) a lot of otherwise good engineers have terrible communication skills and couldn't document their way out of a wet paper bag
2) no engineer ever got kudos, raise, bonus, or promotion for writing good documentation. People do the things they are rewarded for doing.
3) a good tech writer can ask the questions future readers would ask which the engineer takes for granted and doesn't document
Let your engineers do what they're good at. It is building new things, not documenting them.
Once a sufficient body of u
Re: (Score:2)
a lot of otherwise good engineers have terrible communication skills and couldn't document their way out of a wet paper bag
...with a chainsaw in each hand and a squad of Army Rangers to lead the way.
Comment your code (Score:2)
Re: (Score:2)
Have managers who allow time for documentation (Score:2)
If creating and updating documentation is not built in to every project plan/work schedule then it won't happen.
Actual documentation (Score:1)
The key to me is to write actual documentation, not just tutorials. Tutorials are nice for getting people started with basic tasks, but that tends to be all they can do. As soon as users try to do something beyond the stuff you've thought of, they'll struggle. For that, they need to have every user-available control fully documented: what it does in the general sense, what the range of available inputs is, and so forth. Having that information will let people figure out how to do what they want to do, n
how do I find it? (Score:3)
Re: (Score:3)
I store all documentation in SharePoint wikis. SP does a (really) good job of indexing things so it is readily searchable.
Know what it's for! (Score:2)
Don't Wait! (Score:3)
Write your documentation or how-to's as soon as you can. That way you don't forget something,or misinterpret or loose notes.
Re: (Score:2)
Only if you test them for accuracy AFTER you're finished making all the changes.
Pictures and better UI for end users. (Score:2)
Re: (Score:2)
If they're things that a user will be doing once a week or more, how are they supposed to find out how to do them?
Documentation.
Tutorials are good as a part of end user documentation, but they're only part, and should be "unnecessary" in the sense that the information within them is part of the standard documentation.
Get help from someone who doesn't use it. (Score:2)
Everyone in the team has been using it and they are going off of that. They internally know the process and work with that, but someone who isn't in the team has no idea what the process would be.
Personally, I can segment memory and can sit down in front of a manual and forget I've been working on it for a year and pretend like this is new to me.
Ask the new people in the project to read it (Score:2)
Which format? (Score:2)
manpages?
info?
html?
HOWTOs ?
Documentation is sorely lacking (Score:2)
At my last company I came into a role to discover that there was almost no documentation at all. It was all tribal knowledge stuck inside the heads of people that had been there for many years. Needless to say, it was chaotic and frustrating to work in such an environment.
Once I had the authority to do so, I initiated a project to document everything - process flow diagrams, technical design documents, configuration documents, training guides, Wiki pages and How To's. It took a long time but in the end I le
Three things (Score:2)
1. Keep documentation short and to the point. No one wants to read a novel, they just want a quick answer.
2. For APIs, Include examples.
3. For code, don't say what the code is doing.Instead, explain why you are doing it.
--> 3.a. If your code is really abstruse, maybe you do need to explain what it is doing. But it would be better to fix the code, because it is not maintainable.
Recommendation for a Documentation Framework (Score:1)
Make it worth reading (Score:2)
Re: (Score:2)
Refactoring code I found unsanitized user input that was being passed directly to the database. I believe the original variable name was $qp (probably short for query parameters) I renamed it $attack_payload, which was much more descriptive and clearly allowed people to see where they needed to fix security issues
That turned out to be much more effective at getting the SQL injection vulnerabilities fixed than simply documenting them.
Document Early, Document Often (Score:2)
I use Notepad ++ for notes that don't require screenshots, and Word for how-to documentation with pictures. I've also created wikis using WordPress. Full Adobe Acrobat is helpful as well as Microsoft Visio, depending on who you need to share the information with, and what you need to document.
General tips (Score:2)
Start with the big picture. Give people a frame of reference to understand the system and it’s parts. The C4 Model [c4model.com] does a good job at explaining the levels at which you may want to have diagrams, though we find the most bang for the buck if we stop at level 2 or 3 in most systems. Those touch points save so much time later because they give people a framework in which to connect all of the other pieces.
Always, always, always have a detailed and up to date set of steps to get a dev environment operatio
Documentation Tips (Score:3)
1) When you start a new project, Create a rough draft document right up front for each document/procedure needed. This should just be section titles for various tasks the document is meant to cover. A skeleton that you will flesh-out later. Make a ticket to complete it, if you use tickets, and pick a completion date. Also, spell out who the target audience is for the document and write to the least experienced at that level. Do not assume only experts will read your document, most likely it will be novices or people entirely new to this system/product.
2) As you work, fill in the details for each section. When you have a finished working system or subsystem, fill in the details on how to start/stop/use/check/debug/validate. If you have a Test team, this is a good point to bring them in and they can use these details to write their test plans. It does not need to be well written and formmated at first, the polish can come later. Focus on getting the commands and menu choice path in the right areas.
3) When you change something in the code/system, immediately update the affected document(s). Also, let the Test team know it was changed so they can update their test plans.
4) Test your documents by trying to follow it word for word and make changes to make the instructions be very precise. This is where you put the polish on the document. Optimally, another person on your team should try to use it who is overly familiar with the system. The less assumptions and "routine obliviousness" (you do something so often that you are unaware that you do it) the better. If they have ANY questions on how to do something, then the document needs updating with those steps. Add in the formatting and flow. Repeat this step until no further changes are needed.
Overall, documentation is part culture and part personal choice. You need the culture to encourage it and then you need people that choose to do it. All the culture in the world won't change the mind of someone that does not want to do it.
use ChatGPT (Score:4, Funny)
Signed,
Totally not a Practicing Lawyer.
Treat it like code (Score:2)
Most developers already have the skills for good documentation, they just don't realize it because they think they're now doing something different governed by the rules of their high school English teacher.
The purpose of internal documentation is the same as anything else hidden from customers that you still spend time building - to save you time and make your life easier. Just like with code you should
- refactor, delete dead code, Don't Repeat Yourself - documentation that can't be found might as well no
Re: (Score:2)
Most developers already have the skills for good documentation, they just don't realize it because they think they're now doing something different governed by the rules of their high school English teacher.
That's why you hire a tech writer. Developers shouldn't spend time writing documentation, they should write the bare bones, hand it to a tech writer and let the tech writer "make it gooder."
The writer will often need to talk with the developer to clarify or expand items, etc etc.
You don't want developers writing documentation any more than you'd want tech writers writing code. Let them do their thing, working together.
Time spent making documentation is billable (Score:2)
I do enough IT contracting side work, and I almost always get asked why I'm billing for a few extra hours. The answer is documentation, which is as much for my benefit as for the next guy to come through the door.
Write things down, and make diagrams, then go back and explain why your thinking. And then bill your customer for it. They need it more than you do.
Short but complete (Score:4, Insightful)
About getting it short:
About being complete:
About being correct:
Re: (Score:2)
be concise and to the point. (Score:2)
don't write to please yourself or appear smart or professional. simply add the information an engineer will need to approach that component and that is missing from sources, and nothing else. that's all. if you do that you add value. if you do anything else, you just add noise.
so, just unlike your blogpost. you must be a terrible documenter.
*points and laughs* (Score:2)
Writing effective documentation is a surefire way to make yourself expendable.
Who is the audience? (Score:2)
Documentation has different purposes depending on the person using it. Developers need to know how things work behind the scenes while users need to know how to perform tasks. In some situations developers can improve their code writing practices to make it easier to document.
Interfaces can sometime be designed to make documentation easier. When I develop a desktop GUI application I try to identify user accessible functions and whenever possible designate a menu item. Shortcut key combinations and toolba
Documentation is almost like a Diary to me. (Score:1)
Smart Brevity (Score:2)
Good documentation conveys the truth, clearly and accurately, in the shortest possible time.
Use fewer words (Score:1)
Re: (Score:2)
20 year-tech writer here. Don't wear a voice. Just say the thing, using as few words as needed for clarity.
Same same, but ~30 years in harness.
"All Hail the Tech Writers, Who Will Save Us From Ourselves"
Remember you are not writing to impress the reader (Score:2)
Make it Sesame Street readling level. (Score:1)
Serious. Write it so an 8 year old could follow it, preferably with illustrations.
8 year old Sesame Street reading level (Score:1)
Well, at least I HOPE your average 8 year old can read a lot better than the target age for Sesame Street.
Your overall point is sound: "Back in the day" - meaning 40-50 years ago - most newspapers wrote at about an 8th-grade reading level.
Yeah (Score:2)
Time to re-watch Se7en.
Put examples in your docs (Score:2)
Don't assume your reader can formulate a working example from your long thought out paragraph(s). Include examples for every situation mentioned. You'll be glad you did when you need to revisit your project years (or even months) later.
Most important part of the Job (Score:1)
1. The act of writing it all down helped cement it all in my mind
2. Hire a new IT guy - no problem! Easy to read docs (with pictures!) are available for everything. Makes the learning curv
My article, published in SysAdmin in '06 (Score:2)
Egoless Documentation.
Re: (Score:2)
/. didn't like my link.
https://24.5-cent.us/egoless_d... [5-cent.us]
Re: (Score:2)
There are these people called "technical writers" (Score:2)
It's been decades since I've worked at a company that went out of its way to hire technical writers and embed them with the developers to help write and maintain the documentation. And for some reason or another companies I work for have moved away from hiring QA as well: the company I'm doing work for has no QA testers; we developers are expected to test our own code.
I'd like it if we could move back to the days where we hire technical writers and QA engineers and testers; we need to remember that the best
Documentation should be living and integrated (Score:3)
This means that it is both easy to access, and easy to keep up to date, especially from the people who have the most knowledge and are most inclined to do it.
A corollary to this to this is that there is no worse documentation than dead or never-read, regardless of how well-written it is.
Doc, sample code, plus wiki (Score:2)
My favorite doc format remains a curated linked doc set that appends user wiki space / forum for additional content below.
That way, when doc author says âthis can be used for reading configâ(TM) , users that encounter permissions errors, format errors, etc can discuss those edge cases. Weak sample code can be replaced or extended. Typos or suggested hacks or âsee alsoâ(TM) links can be annotated.
Granted, the vitality of the project is a factor â" docs need to be used to gain vital
Long dead (Score:3)
Good documentation died when Unix took over. ...A long long time ago. What happened was that actual manuals written to help a user were replaced by an infinity of man pages.
The difference is like that between reading a biology book and trying to read all the papers in the field.
Microsoft took it to another level, writing self-referencing documentation which is just filled with useless tautologies, no doubt written by people who have no clue what the stuff actually does.
Workflow for GOOD documentation (Score:2)
I hate the term "living documentation" because usually it refers to some half-assed, incomplete spec but in this case it applies. Documentation is a continuous process.
First, you need management on board to understand that it takes time and effort to have documentation and to keep it updated. There is almost nothing worse then a wiki / confluence page that is out-of-date.
Second, there are multiple kinds of documentation. ALL of them are important:
* Getting Started
* Process / Workflows
* HOWTO. i.e. How d
kinds of documentation (Score:3)
Ok, briefly, what I've seen from decades in IT, is that a company typically provides two of the four kinds of documentation needed for a new product... what, the ol tag doesn't work in Slashdot? Sigh, ok then.
Generally the documentation you get is a User's Manual and a Reference Manual. The User's Manual tells you all the things the product CAN do, but not HOW. The Reference Manual tells you HOW to do everything the product can do in excruciating detail.
What's needed are two more documents. The first is a solutions guide, giving procedures for the most common usage of the product. Something to make it operational and start to foment understanding. And the last, and most important, a Quick Start guide, giving basic instructions on how to bring up the product and communicate with it. For instance, if it's a piece of network gear, how to configure it to talk on the network and at least get basic functionality going.
But what you usually get is a slim document saying "you can do THIS and you can do THAT", not much more than a marketing handout, with no indication of where to start to do these things, and a lugubrious reference manual which gives you a bunch of data with no context. (Of course, you do need the reference manual, but more is required.)
An example from long ago, I purchased a terminal server that came with a six page booklet telling me its capabilities (ok, fine) and a reference manual the size of a phone book. In the typical interrupt driven world of a systems administrator, we don't have time to become the subject matter expert of every piece of new gear. We want to get basic operation going and then dive into the details as necessary. Typical documentation doesn't give us that.
Even worse, there seems to be a tendency in this day and age to make what documentation the vendor provides the bare minimum, with the idea that companies will engage professional services to fill the gap. Typically, the admin will use customer forums to fill the gap, but this paradigm tends not to work for really new products.
In summary, what I want to see is (a) Quick Start Guide: How do I get the box up and talking. (b) User Guide: What does the box do? (c) Reference Manual: Document every detail. (d) Solutions guide: Procedures to do the most common things.
If you want your documentation to be effective, that's what I want to see.
From Slashdot itself, some useful concrete steps. (Score:2)
https://m.slashdot.org/story/1... [slashdot.org]
Which leads to: https://stevelosh.com/blog/201... [stevelosh.com]
And that leads to the absolutely BRILLIANT article:
https://www.americanscientist.... [americanscientist.org]
URLs 2 and 3 have concrete suggestions.
I will add two more: write--or more importantly, EDIT--with your reader in mind.
Never assume your reader knows already. Explain your acronyms, footnote your assumptions, diagrams speak volumes.
How to comment code (Score:2)
I think code should have these comments:
1. For some functions/methods, document at a high-level the *contract* of this function i.e. what it expects and what it produces. This is never needed if the function's name or type signature provide those unambiguously, as is commonly the case for "leaf" functions in your codebase. But for the higher-level functions, e.g. "void handle_on_type_formatting(int line, int column)" then you need to document the contract.
The reason to document the contract is partly so tha
Learn How To Spell (Score:2)
Grammar and spelling mistakes introduce ambiguity, and may frustrate the reader. If your language skills aren't great, find a colleague with better language skills than you and have them review/tweak your work. Others will be glad you did, and you might level-up a bit too!
At least write an Approach Document and Comments (Score:2)
The absolute minimum required documentation is an Approach Document that describes the purpose and/or problem, lists the various ways it could be solved including pros and cons, and then outlines the actual solution. That, along with decent code comments, delivers the high- and low-level information you'll need to be able to support your code after an eternity (6 months) has passed.
some guidance (Score:2)
I am going to excerpt here from my upcoming book on AI and knowledge management.
This is super-summarized and very terse, sorry, not enough space here. This is a meta-orientation to writing the material.
Keep in mind that much tech documentation is the navigable expression of knowledge models. That means it is done to help the audience learn the structure and content of knowledge carried in a model, and to find things in it. So you want to have both content giving information, and an arrangement of the inform
The only documentation you need: (Score:4, Insightful)
1. wipe out your dev environment (no, don't mean recreate a vm based your ready image)
2. recreate it only following your docs.
3. produce a full build that is usable to your use case. Again, only following your docs.
done. no step 4. no profit either. By the end of the exercise you will have good docs.
Just have to remember to run these steps every now and then.
Learn to write concisely. (Score:2)
It comes with practice.
The book The Elements of Style helped me.
"Do not take shortcuts at the cost of clarity."
That one bit of advice from the book has served me well.
Check out the NASA guidelines (Score:2)
Re: (Score:1)
Which is why DEK named his programming system Literate Programming:
https://www.goodreads.com/book... [goodreads.com]
I really wish this was more prevalent, and better supported --- that said:
http://www.literateprogramming... [literateprogramming.com]
makes for interesting reading and has some really cool texts such as:
http://www.literateprogramming... [literateprogramming.com]
Re: (Score:3)
DEK should have named it prolix programming. He is at the opposite end of documentation: tl;dr. He goes on and on and on to the point where the gist is lost.
I'm a big fan of DEK, but not of his verbosity.