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...
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 ...
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...
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]...
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)....
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...
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...
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...
We did not find an off-the-shelf solution to this and built our own. I'm not the author and can't release the code, but here is an overview of the approach. Flare versions from 2016 onward support...
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...
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...
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...
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...
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...
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...
It depends on how formal the context is. If you're writing a short blog post about getting started with a new game, "you'll" probably won't be out of place. If you're writing a tutorial as part o...
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...
