Writing Stack Exchange
Writing Stack Exchange

Questions tagged [examples]

Creating, maintaining, and presenting usage examples in documentation.

Examples in documentation can include code, graphics with "fake" data, web sites, and more. Examples are usually tightly coupled with the documentation containing them but often need to be created and managed externally. (For example, code examples need to be compiled and run.)

11 questions
22
votes
7 answers

Best practices for maintaining documented code examples?

A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically showing only the relevant excerpts from the sample…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
11
votes
6 answers

Demo data in screenshots! What are the best practice?

My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making screenshots. I mean demo data, such as Name, Company…
Yuliya Drygybka
  • 111
  • 1
  • 1
  • 3
10
votes
5 answers

What are the benefits of including complete working code samples in documentation

When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding language, a "hello world" style sample API client…
Lefty G Balogh
  • 554
  • 5
  • 8
10
votes
2 answers

Good Examples of and Practices in Code Documentation

I noted in this question: What is the best way to learn technical writing? ...that a rated method to learn how to write technical documents is to imbibe good examples. Can you recommend any examples of good code/ database documentation that have…
Stefan Piskorski
  • 115
  • 1
  • 6
8
votes
3 answers

'for example' and 'e.g.' in a thesis

I'm writing a thesis in English (I'm not a native speaker) and I suddenly wondered: should I use 'for example' or 'e.g.'? should try to completely avoid both? There are no university specific recommendations for it afaik and other thesis in my…
Cold_Class
  • 183
  • 1
  • 7
3
votes
2 answers

Putting code examples in BSC thesis

I am writing my bachelor's thesis in software engineering. It is split into two parts: a theoretical part where I analyze existing literature, compare models and draw conclusions; and a part where I present my software solution to a problem using…
David Szalai
  • 133
  • 4
3
votes
1 answer

Is there any screenplay which is widely considered by screenwriters to be perfectly written?

Is there one Screenplay that is an example of being perfectly written by the majority of screenwriters that they keep at the ready to refer to while writing their own works? I was hoping to learn of one example of words either written or an image…
Doug6388
  • 41
  • 1
2
votes
5 answers

How to structure a sentence containing long code examples?

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sentence containing "before" and "after" examples which…
Dave Jones
  • 153
  • 6
2
votes
3 answers

Copyright of examples used in books?

I'm getting into non-fiction technical writing (a blog, but potentially ebook or otherwise). Often the best technical advice come from dissecting and synthesising good and bad examples from the industry. Basically, I want to take screenshots of a…
Pie21
  • 129
  • 2
0
votes
1 answer

Providing examples for the sake of it

I am writing an academic text about linguistics. I have managed to obtain examples from endangered languages that are rarely included in research (one in particular has less than 500 speakers according to the UNESCO Atlas of the World’s Languages in…
user51579
  • 9
  • 1
0
votes
1 answer

Find error in this sentence

Do not/ get panicked/ in emergencies/ no error. I think,here 'panicked' is an adj, and hence 'no error' . If it is not so....then please suggest the right ans...
user28796
  • 1