Skip to content
 
If you can read this, either the style sheet didn't load or you have an older browser that doesn't support style sheets. Try clearing your browser cache and refreshing the page.

(Some Guy)   You don't have 'too much documentation,' according to a person who apparently doesn't have any documentation at all   (gamedeveloper.com) divider line
    More: Misc, Web page, Information science, Figure It Out, Need, 2008 singles, Document, much documentation, pages of empty documentation  
•       •       •

1030 clicks; posted to Fandom » and STEM » on 13 Sep 2021 at 10:19 PM (6 days ago)   |   Favorite    |   share:  Share on Twitter share via Email Share on Facebook



20 Comments     (+0 »)
View Voting Results: Smartest and Funniest
 
6 days ago  
"Too much is always better than not enough."

- "Bob"
th.bing.comView Full Size
 
6 days ago  
As someone who has done technical writing in past positions, find the balance between simple and right to the point of being a little too technical. Include screenshots of what you're explaining within the document, and use standard formatting. It's not hard, but if you don't have a knack for it; it won't help anyone.
 
6 days ago  
"When titling a page, don't just name it what you think the page is about - name it what any user should know the name is about."

Uh, wat?
You wana take that from the top?
 
5 days ago  

Space Station Wagon: "When titling a page, don't just name it what you think the page is about - name it what any user should know the name is about."

Uh, wat?
You wana take that from the top?


Don't assume a meaningful name to you is meaningful to everyone. Title things in such a way that if a random coworker found the document they would know what it was about.
 
5 days ago  

Space Station Wagon: "When titling a page, don't just name it what you think the page is about - name it what any user should know the name is about."

Uh, wat?
You wana take that from the top?


Yeah.  The writer knows what the page is about.

The USER knows what they're looking for.  The manual is for users.  To use.
 
5 days ago  
I get the concept I just think that sentence is clunky.
 
5 days ago  

Space Station Wagon: I get the concept I just think that sentence is clunky.


Valid.
 
5 days ago  

BafflerMeal: Space Station Wagon: "When titling a page, don't just name it what you think the page is about - name it what any user should know the name is about."

Uh, wat?
You wana take that from the top?

Don't assume a meaningful name to you is meaningful to everyone. Title things in such a way that if a random coworker found the document they would know what it was about.


That's actually a very important advice. The first thing you should ask yourself, when writing documentation, is, who are you writing it for? Is it a maintenance guide for your fellow developpers ?  Is it a support tool for the helpdesk guys ? A training tool for end-users ?

There is a document we write at our company, that actually has the issue of being aimed at two very different sets of users : the power users that need to approve what we are going to implement, and the developpers who will develop the solution. So the technical parts are unreadable to the powers, and the description of business rules are both difficult and of no interrest to the developpers.
 
5 days ago  
No orphaned headers, always included PCO (purpose, context, organization), and you never need more than three levels of headers.
 
5 days ago  
The code is the documentation you illiterate bastards. Can't read it? Great, you just qualified for management.
 
5 days ago  

NathanAllen: The code is the documentation you illiterate bastards. Can't read it? Great, you just qualified for management.


Sure it is, $NathamAllen, sure it is.
 
5 days ago  
Pro tip: never let engineers write user documentation.

I used to be a tech writer/graphic designer back in the paper age for an international company. What fun that was. This info needs 10 pages to be understandable, you get 4. There are 12 different cable types, each with its own colour, when printed black and white 12 different cables becomes 6 or 7. Changing the thickness doesn't help much and due to technical issues with the publishing software, we couldn't use dashed lines (or tiny text) without images going all screwy.

I was part of a development team and sent out a set of guidelines and best practices to write documentation with a canary trap: all commissioning instructions must be written in iambic pentameter. Nobody caught that one. I suspect nobody read the damn thing to begin with.

Our egg headed department manager  thought because we maintained the documents, we could do whatever he felt like we could do with them. There was a major problem with sub-contractors frying components because they weren't taking ESD precautions when installing stuff. The documentation was clear on the subject but he wanted us to improve that somehow. All 10,000 documents without input from the SMEs or document owners. I informed him it wasn't our problem, nor the company's and we didn't have to do anything. Literally, there was nothing we could do from a documentation standpoint. Boy was he pissed at not getting his way.

Assume that end users never read what you write, or misinterpret even the most basic of information.
 
5 days ago  
I work for a company that has vast, untamed gigabytes of documentation on everything. Endless intranet pages on employee resources, training, news, short and long term plans, logos & color schemes, etc. It is being generated and developed and updated and refreshed at all times, year round.

No one reads any of it.
 
5 days ago  
Someone once said we shouldn't call the people who use our software "users" since they're not on drugs. But when I start seeing and hearing the things that they do, I begin to think, "I don't know..."
 
5 days ago  

NathanAllen: The code is the documentation you illiterate bastards. Can't read it? Great, you just qualified for management.


I have never known this to be true.
 
5 days ago  

NathanAllen: The code is the documentation you illiterate bastards. Can't read it? Great, you just qualified for management.


You are not the virtuoso you think you are.  No one wants to read your code.  Your code sucks.
 
5 days ago  
How about "Include by reference."

The AAR  MSRP for Locomotive Architecture is about as thick as the tax code.  Of course, it governs safety critical systems that keep trains from coming off the track and crushing you as you wait patiently at grade crossings, so that is OK.   But it is managed by the AAR and updated on a regular basis.

But what I hate more than anything is folks insisting "You need to document that!" when it is already in the goddamn documentation.  Just not ours.   I can't tell you how many times I've come across "documentation" that was basically just a cargo cult copy/pasta from those documents into ours, and now ours is out of date.

A simple "This widget will adhere to standard AAR S-666 revision 1234.  Refer to that document for more detail" would have been more concise and accurate.
 
5 days ago  
Fandom?
 
5 days ago  
Ask anyone who is about to be thrown under the bus for someone else's screw-up:

Never enough documentation
 
5 days ago  

Rent Party: NathanAllen: The code is the documentation you illiterate bastards. Can't read it? Great, you just qualified for management.

You are not the virtuoso you think you are.  No one wants to read your code.  Your code sucks.


You get me wrong. My code is the kind of trash written to barely function.

It's all in there, documented in the code.
 
Displayed 20 of 20 comments

View Voting Results: Smartest and Funniest

This thread is closed to new comments.

Continue Farking




On Twitter


  1. Links are submitted by members of the Fark community.

  2. When community members submit a link, they also write a custom headline for the story.

  3. Other Farkers comment on the links. This is the number of comments. Click here to read them.

  4. Click here to submit a link.