Posts by Monica Cellio
Handling realistic jargon that your readers might not know is similar to the problem described in Using real words from a foreign culture feels like 'Calling a rabbit a "smeerp"', a question about ...
I've changed teams (and companies) since asking this question years ago, and the doc set is even larger on my current team. Here's how we manage changes that affect parts of the documentation with...
This might be related to this issue, which is sort of the reverse of the one I'm reporting now. According to the front page, ArtOfCode did something on this question an hour ago (as I write this)....
When we launched this community, we did not yet have the ability to set different reputation grants for different categories. We've had this for a while but we failed to follow up before now, sorr...
We publish a substantial documentation set online. Each page has a place at the bottom that asks "was this helpful? (Y/N)", and if the person chooses "no" we offer a textbox. We collect all this ...
In our documentation of SQL functions and statements, we include a BNF-style syntax summary. As is conventional, we indicate optional elements in square brackets, like this: CREATE [IF NOT EXISTS]...
We just got hierarchical tags. A tag can have one or more children, and when you search on a tag you can either search just that tag or also search its children. This gives us another way to orga...
You might have noticed the new "categories" feature on this site. I mean this: What are categories? Categories are types of content -- main Q&A and Meta are the two that all sites share, b...
According to the question list, this question was last active 8 hours ago as I write this: However, I answered it 2 hours ago as shown in the history on my answer: Is this list heavily cached...
I've realized in using this site how dependent I am on the information on the SE question list about who and what bumped a post. "Answered by" + name is a valuable "hey, go read this!" clue, as do...
We produce a large HTML documentation set with the conventional two-pane view: expandable table of contents on the left, selected topic on the right. When you select a topic, if it has subtopics --...
There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form ...
Summary: I'm looking for a way for reviewers to comment collaboratively as close to "inline" as possible on a large HTML project. The problem in detail I work on a team that documents a large pro...
In your question you talk about writing "a scietific journal" (to track your progress), but then you talk about publishing in industry journals. Those are not the same thing -- and when you submit...
Using "he/she" will annoy some of your readers; using singular "they" will annoy others. And referring to a user as "it" will seem weird to most people. What I do is to write around the problem wh...
I endorse Evil Sparrow's answer. If, however you must lead with the old man for some reason, you can return from the room back to him with a paragraph break. Paragraph breaks are (small) disconti...
As Viktor said, FrameMaker is probably the best widely-used tool for doing what you're trying to do. Another (Windows-only) tool that I'm using now is Madcap Flare, but it's pretty pricy. Other...
We use Madcap Flare for a large documentation set, with HTML output. (Flare source is a very HTML-y XML with some Flare-specific additions.) We use git for source control and new work is done on ...
One of our community members, Paulster2, has created some ads and submitted them on SE sites where we've advertised in the past. These are "community promotion" ads, meaning the SE communities vot...
A core principle with citation is: if you say it's from source X, it must be exactly what's in source X. Not a summary. Not a translation. Not a refactoring. By citing a source you are invoking...
We use Madcap Flare to produce a large documentation set that contains many code examples (primarily SQL, but also C++, Java, and Python) and command-line operations. When the doc set was first pl...
I received a response from Flare's technical support. There was a bug in Flare's git integration in some older versions (at least 2019r2; not sure how much farther back). This bug was fixed in Fl...
Writing positively about yourself can be hard. It feels like bragging, which feels rude. What I've found helps is to frame it as a specific marketing project. It's not that I would go around boa...
This depends in part on who your audience is, as already noted. It also depends on what kind of editorial support you'll have and on what your goals are. I've seen lots of work, both drafts and p...
If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and...
