|
I truly appreciate those who create quality freeware, but "Hey, it's free" is no excuse for poor documentation. For example, let's say there is a property, Object.CanJump. And in the docs, it only says something like, "Boolean. Gets or Sets whether the object can jump." So I look up "Jump" in the docs and all it tells me is maybe what NameSpace it's in, and then refers me back to the CanJump property.
Unless there's a thread in a discussion forum somewhere or the author will actually answer an email, you end up banging your head on the wall trying to figure it out. Taking an extra 10 minutes to better explain the property and what it refers to is not too much to ask. 
Sometimes the true reward for completing a task is not the money, but instead the satisfaction of a job well done. But it's usually the money.
|
|
|
|
|
I prefer Markdown (or similar), as it lets me write documentation in the environment where I'm most productive - my text editor! And it's so easily convertible to other formats (Word format even!) using Pandoc or similar tooling! Same can be said about AsciiDoc or reStructured Text - but a text-centric format is what I prefer...
In the past, we've used Docbook with the (now missing - thank goodness I configured it!) e-novative Docbook environment to produce HTML, CHM and PDF variants of our technical documentation using XSLT and XSL-FO, but the pain of maintaining the Docbook syntax (it's XML! Blegh!) just isn't something I want to be doing any more...
Java, Basic, who cares - it's all a bunch of tree-hugging hippy cr*p
|
|
|
|
|
If its over a few lines of text I use MS Word(or some other full powered word processor) then will copy and paste it to where it needs to be. (markdown, text, html, etc...)
|
|
|
|
|
... only if you supply me with a usable WYSIWYG editor.
Okay, anything if you supply me with a usable WYSIWYG editor.
|
|
|
|
|
What software do use to write the first, or early, versions of tech docs ?
What software do you use to edit, format, style, etc., tech docs ?
The answers to these two questions would then, imho, need to be interpreted in terms of the context:
1. in your work, do you write/edit tech docs ? use reporting tools ?
2. do you use any comments-to-structured text tools in your code ?
3. do you use any templates for technical docs ? use mark-down tools
4. is your documentation intended for print, or web, or both ?
I'd be a better person if I stopped paying attention to such details ?
cheers, Bill
«There is a spectrum, from "clearly desirable behaviour," to "possibly dodgy behavior that still makes some sense," to "clearly undesirable behavior." We try to make the latter into warnings or, better, errors. But stuff that is in the middle category you don’t want to restrict unless there is a clear way to work around it.» Eric Lippert, May 14, 2008
|
|
|
|
|
For that 12+ percent in the survey who don't write documentation, I look forward to the day you have to maintain someone else's code with the same attitude. Say about 50KLOC unsupervised code written by a cowboy with 1 year non-commercial experience, and the only comments are the programmer name.
Think it won't ever happen? If you don't learn to write you'll never get past coder, and eventually you wind up as the maintenance guy. Remember that thing about karma, and how what goes around comes around?
Jack Peacock
|
|
|
|
|
There are a lot of programming positions where you aren't allowed to write documentation, as both the requirements and the documentation are written by others and thou shall do only what has been ordered to you to do. I have several friends in such positions, most of them work for different branches of a big multinational consulting company with a strong Accent on manure.
Not my kind of job but if that would be the only way to survive...
DURA LEX, SED LEX
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
If you think 'goto' is evil, try writing an Assembly program without JMP. -- TNCaver
When I was six, there were no ones and zeroes - only zeroes. And not all of them worked. -- Ravi Bhavnani
|
|
|
|
|
At least there's documentation to start. But even in that kind of position it doesn't excuse not commenting the code. I use XML standard for C#, Doxygen standard for C and assembly. Descriptions for modules, methods, classes, interfaces should still be in place even if it's just copied from the specs.
Now if you wind up in a job where the head guy bans comments and all other forms of documentation (been there, done that), I built my own manual on the side, made a separate (non-repo) version with comments, and left it all in the desk for the next guy after I got out of there. At least he got back 6 months of his life that I wasted tracing through cowboy code.
|
|
|
|
|
Some "programming" jobs actually ban writing code altogether, relegating the poor fella to run precooked unit tests and report the results. Kind of a brown, foul smelling job imho but it's paid a lot more than mine, which encompasses almost anything save cleaning the toilets.
DURA LEX, SED LEX
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
If you think 'goto' is evil, try writing an Assembly program without JMP. -- TNCaver
When I was six, there were no ones and zeroes - only zeroes. And not all of them worked. -- Ravi Bhavnani
|
|
|
|
|
JackPeacock wrote: I use XML standard for C#, Doxygen standard for C and assembly. Descriptions for modules, methods, classes, interfaces should still be in place even if it's just copied from the specs.
I tend to write only comments for those but not comprehensively. I tend to shun inline comments in favour of readable code, i.e., introducing small methods or boolean variables that are named in accordance with the comment I would otherwise have made.
Kevin
|
|
|
|
|
It' better than old, misleading documentation. 
|
|
|
|
|
One of the biggest problems I have found with documentation is maintaining it. It may be written, but then not maintained, Almost every time I have been on a project and given a document, it has been more wrong than right. One of my big grips with Microsoft Visual Studio is that they have not enhanced the documentation since almost the .NET was released. The XML comments are just so much work to maintain.
|
|
|
|
|
This is the classic excuse not to write documentation. Using the same logic we should not write code because it always has something wrong with it. Why is it code is maintained but not the comments and documentation that goes with it?
There's nothing inherently wrong with the XML style comments. In fact, just the opposite, it's a standard way to build in comments right along side the code. The VS IDE helps by automating some of the formatting. Claiming comments are so much work to maintain can just as easily be applied to the code itself. It's just so hard to find and fix bugs, let's deploy without testing and let the user work around the errors.
Oh, wait, all too often that IS what happens. I stand corrected, comments are hard.
|
|
|
|
|
May issue is that in Visual Studio there is very little done to help with maintenance of XML comments.
1) Comments can be long, and there is no wrapping provided. This discourages making longer comments, and cumbersome to update.
2) Change the signature of a method, and tags for the arguments no longer are right. The automatic generation works fine when first used, but not after that.
3) Visual Studio should encourage using common names so that only have to document an argument or variable once, and one comment is reused. Notice I used variable, which is not supported by XML comments.
It was a good start, but has not been taken further.
|
|
|
|
|
Clifford Nelson wrote: May issue is that in Visual Studio there is very little done to help with maintenance of XML comments. 1) Comments can be long, and there is no wrapping provided. This discourages making longer comments, and cumbersome to update.2) Change the signature of a method, and tags for the arguments no longer are right. The automatic generation works fine when first used, but not after that.
GhostDoc/CodeRush/ReSharper help here. But, of course, these aren't out of the box and they're not free.
Kevin
|
|
|
|
|
This comparison is quite unfair. Comparing a whole format familly (office suite document formats) to several single formats seems to be a bad idea.
Grouping formats differently shows that office suite formats (that require heavy tools) are less used than plain text and its derivatives (markdown, latex, xml, ...) that can be edited with any light (or not) text editor and managed efficiently any SCM.
|
|
|
|
|
The grouping seems reasonable to me; the intents of all the word processor apps is the same and for basic usage they all work the same. Especially since you can generally save all the relevant formats with any of the major editors.
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, waging all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
|
I actually kind of like OneNote now but it has been a hard adjustment and the cause of many internal meetings.
Eric
|
|
|
|
|
We love to use OneNote for our documentation. Maybe a steep learning curve?
|
|
|
|
|
Not forced, but I use OneNote and like it. What's your problem with it?
|
|
|
|
|
|
There is usually no need of more than a clear chapter/paragraph division and readable titles. Kudos to softwares with auto-indexing and clickable links.
DURA LEX, SED LEX
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
If you think 'goto' is evil, try writing an Assembly program without JMP. -- TNCaver
When I was six, there were no ones and zeroes - only zeroes. And not all of them worked. -- Ravi Bhavnani
|
|
|
|
|
|
nice one. 
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
