Documentation workflows based on Markdown and GIT
Scribe: Matt Ness
- GIT and Markdown go together; GIT uses text files and opens in Markdown by default
- Writing documents in GIT enables you to use the same content workflow as your engineers
- Markup does not enable the same amount of formatting capability as other authoring tools, though you can augment it with HTML
- Good editors- Notepad++, SublimeText, Atom, MarkdownPad
- Kamodo- have good markdown support
- Markdown is a markup language- how is it implemented. One of a family of text based languages- intended to be easy to use. The markdown site gives you a WSYSIB view of your output.
- Scribe has contract job where he was asked to use XMGTAL, but this is not good for his project, Markdown advantage; used to let developers into GIT. Not as flexible as Word or Framemaker w/r/t styles and formatting. Markdown is like simple HTML.
- Markdown may be too simple say some.
- Discussion of formatting-you can do a lot with its basic markup and then add HTML for advanced formatting.
- Pandec is a good markdown- HTML converter is very scrib similar with markup.
- You do not need to add HTML/CSS to it, would look like HTML 3.
- Sequence is CSS does not apply until markdown is converted to HTML.
- Chrome extension to view markdown
- Markdownpad- view/edit markdown files
- How do you generate markdown structure
- GIT- using for documentation- Use to monitor changes to documentation and track changes
- Discussion of GIT workshops- all internal communication are managed through GIT
- These are organizational issues, not technical issues. GIT respositories use Markdown by default.
- When you do your pull requests- same as source code- the doc reviews.
- Writing for it, publishing it, managing localized content, process engineering, best practices
Scribe: Alan House
- Preparing your conduct- Acronyms is ideal, other “checking” mechanisms exist
- Localization- local acceptance is important- GIGO
- Human workflows are still best
- Make sure you own the TM
- Machine translation is you have training data
- How to prepare your context for localization?
- Some LSPs will localize screen shots
Metadata and Categorization strategies for technical writers
Scribe: Shari Clare
- Mindmapping can help define content structure
- Once you have the correct structure, content can be moved to be correct document type
- Metadata is useful for: metrics, governance (where content can be used), finding information faster, getting more information of what something is, “Is-ness”- the difference of what something is
- Google is a mindmapping tool, which helps you figure out the structure so you can put content into the right document
- Reuse of content is one of the goals
- Standards can be used as categories to help identify parts of data, which can be put together or to a whole document
- Mental structure analogy is like Amazon, which lists topics, then drills down into a variety of categorie
- Taxonomy falls under the field of information architecture
- Smartlogic is a tool for managing tazonomies
Introduction to Data Modeling: How to Start Thinking About Reuse
Scribe: Guy K. Haas
- Understand the problem- what elements are constant in repetition, and what are variable
- In your tool, determine what functionality(variable,conditional, snippet or text inset) to use
- Data modeling has a long ramp- up time when it comes to re-use. Rules for naming, categorizing, etc. But it pays off at translation time
- Governance processes might be necessary depending of scope of project. If someone else might take it ever, or if multiple authors are involved– need to document the logic of the reuse
- Some tools are better than others at supporting governance
- Need management of governance
- Establish the atomocity of reuse
- If a topic has more than 20% of its content as reused material, split it.
- Leveraging LinkedIn to get yourself noticed. Since Andrew spoke last January, they’ve totally transformed the UI and many of the features, so even someone who attented last year will get value from the presentation.
Scribe: Peter Jew
- Any power wars? Moderate. Try to update regularly so they won’t forget.
Too much update- recruiter gets triggered and get calls
- In mind is one advantage, but it has become very hovey.
- Sometimes you get someone who already connected with
- Get recommendations and references
- Get consistent references- you can edit and work with the recommendations
- Best way to get a recommendation is to ask the person to recommend yo and tell them what you wanted to be.
- You should also rejuvenate
- Goggle search- add “tech writer”
- Most recruiter will go to LinkedIn first before they post a job
- You can restate the skills last at the bottom
- If a recruiter contracts you, respond even if you don’t need a job.
- Other people may mind your network and connections- you can set visibility on connections
- Add photo
- Keep your resume more detail and specific to the job- LinkedIn should be genuine and lots of keywords
- Join LinkedIn groups and keep abreast of head
- When browsing for jobs- stay obscure if desired
- Premium gets directed email and advanced search
- Job seekers may get premium and get to the top of the list
- You can contract recruiters via twitter
Writing/Formatting Best Practices
- Standards as they apply to the technical writing profession, process, and data items.
Scribe: Karl L. Leader: Bonnie
- Depends on context, audience, etc. “Never any absolutes.”
- Semantic markup lets device and style sheets determine look and format, using some tag and each case.
- Best practice for typography may not be same as tech writing
- Automate formatting
- All differences have to be “neat”, be consistent as much as possible. Not arbitrary inconsistency- (yet maybe appropriate with informal tone)
- Proposal: 2 levels of headers, level 3 gets blurry.
- Scemantic tagging= fonts/formats imply meaning. Made with code “what it is” not represents, emphasithes. Categories
- If topics maybe heirararcal or equal depending on context.
- Use a minimal number of headers, no more than necessary
- Conceptualize device format “large vs small” not “mobile vs desktop”
- Have a style guide and use it! Different devices have new action verbs. Eg. “cick” vs. “tap”. Write specific to device or more generic terms like “select”.
- Research= Trend m mobile.(Apple uses no numbers)
- Steps in procedure do not have to be numbered.
- Priority is to fit content on smaller screens rather than numbered list. But very technical does benefit from if steps.
- Strong based tutorial,no numbers.
- Move to casual tone of voice- moving to allow contractions- even in LBM style guide R MS style guide
- (Advertising seldom was complete sentences)
- People jump to images, sleep text blocks
- (A lot of tech writing rules are based on research)
- IEEE professional communicators publishes academic journal.
- How many have done usability testing of content.