Tag Info

New answers tagged

0

The code is already a form of documentation of what the system does. That is rather much the point of high level language code, to ease the understanding of systems for human readers of it. This is a hint to a solution. Ask yourself, "who is the documentation for?" Is it for programmers to communicate to other programmers within your organization? Then do ...


1

This is a hard problem. Unless your company has the resources to do full reviews of all the documentation on each release -- and if they do, I wonder how they stay competitive -- then you are at risk here. In my experience you can do some things to address the problem when it happens, and some things to reduce its chance of occurring. Here are techniques ...


-1

I'll give you an answer not as a writer (I don't write technical documentation), but as a user. You want to sell your software, because selling your software will give you a job as a writer of software documentation. You sell your software by great user experience. Great user experience relies to a large part on easy to use software documentation. So making ...


2

I am just sharing the guidelines I work by. If required, we can discuss the reasoning behind these guidelines and may be even specific examples. (Say, for example, beyond maintainability, yet another reason text is better for less-than-complex steps is search engine optimization.) When to use screenshots? You need the context of the UI to make a targeted ...


2

In the absence of a style guide saying otherwise, your approach is fine. (So is abbreviating to "Fig.", though I prefer to spend the extra three letters and use the full word. It's also consistent with "Table", which I haven't seen abbreviated as "Tab.".) Whatever you do, be consistent -- refer to all of your figures as "Figure N" and use that same text ...


0

Left to my own devices, I don't use figure numbering (or table numbering either). However, I have worked on some assignments where its use was mandated by the corporate style guide. I always insert images right where I discuss them and make sure I use formatting that will keep the figure with the related text. In that case, there's no need to refer to the ...


0

I would rewrite that sentence completely as: You may delete servers that do not have customers assigned to them. Note that I also removed the unnecessary capitaliztion.


4

You can write the FAQ in a mixed fashion. Depending on what the actual question is, you could choose any of the three styles (or maybe alternate styles too) that you have mentioned to frame that particular question. The idea should be that the readers find it useful. If it is something obvious, then the style differences might not be too much of a deal. For ...



Top 50 recent answers are included