--- title: "Review of Structured Writing: Rhetoric and Process" id: "13572" type: "post" slug: "review-of-structured-writing-rhetoric-and-process" published_at: "2018-11-04T12:20:34+00:00" modified_at: "2018-11-04T18:46:12+00:00" url: "https://www.cherryleaf.com/2018/11/review-of-structured-writing-rhetoric-and-process/" markdown_url: "https://www.cherryleaf.com/2018/11/review-of-structured-writing-rhetoric-and-process.md" excerpt: "Mark Baker has published a new book called Structured Writing: Rhetoric and Process. It is probably the most important book on technical communication since Anne Gentle’s Docs Like Code. In this post, we’ll look at what the book covers. We’ll..." taxonomy_category: - "book" - "DITA" - "Technical Communication" taxonomy_post_tag: - "book" - "DITA" - "Every Page is Page One" - "structured content" - "structured writing" - "technical communications" --- Mark Baker has published a new book called [Structured Writing: Rhetoric and Process](https://xmlpress.net/publications/structured-writing/) . It is probably the most important book on technical communication since Anne Gentle’s [Docs Like Code](https://www.docslikecode.com/book/) . In this post, we’ll look at what the book covers. We’ll also include quotations from Mark’s book and his website. ## About the book The book provides an overview of structured writing techniques and systems, the challenges with each of them, and suggests a different approach to structured writing. ## What is structured writing? > “Structured Writing is a tool for managing the complexity of your content system and making sure all of that complexity gets handled by people with the right skills and resources. The ultimate objective is to enhance both process and rhetoric.” > > “Structured writing is simply the technique you use to partition and transfer complexity around your system so that everyone on the team can do their jobs better.” ## The different writing domains The book begins by explaining the different content domains: - Media - Document - Management - Subject Mark uses recipes as an example throughout the book, so let’s continue using that. Imagine you are a writer who has to publish a recipe for flapjacks (the British version) onto a number of different websites: [https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/Feelgood-flapjacks-recipe.png?ssl=1](https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/Feelgood-flapjacks-recipe.png?ssl=1) [https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/flapjack3.png?ssl=1](https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/flapjack3.png?ssl=1) [https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/Flapjacks3.png?ssl=1](https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/Flapjacks3.png?ssl=1) [https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/flapjacks.png?ssl=1](https://i0.wp.com/www.cherryleaf.com/wp-content/uploads/2018/11/flapjacks.png?ssl=1) You can see from the images above, they use different colours, fonts and layouts. They differ in their use (or not) of lists. They have links to different related topics, in different parts of the document. ### Writing in the media domain If the writer is working in the media domain, the presentation and the content are “baked” together in each individual website. The writer has to think about (and create) the typography, design and words. If they want to make a change to the colours, font sizes, layout, links, or words, they have do this in each individual document. ### Writing in the document domain If the writer is working in the document domain, the media domain issues are partitioned and moved outside of the document. For example, they can move the decisions on the colours and font sizes to a cascading stylesheet. They only need to make a change to the stylesheet, rather than each individual web page. Someone, or some thing, can manage that issue for the writer. ### Writing in the management domain If the writer is working in the management domain, the writer can move some (but not all) of the linking and content management activities to a content management system. However, Mark states they are recording how the content is managed, in with the content. If they want to write content that is specific to a particular type of user or product, they need to create conditional text. For example, they might need to replace an ingredient with an alternative, so that the recipe is suitable for people with specific dietary needs. ### Writing in the subject domain If the writer is working in the subject domain, they only write about the subject matter itself. They can focus on writing the recipe, and defer the decisions on the typography, design and linking. The media, document and management domain elements are recorded and managed for the writer elsewhere. ## How we write today > *“Most current structured writing systems are either wholly or principally document-domain systems.”* Side note: In fact, primary school children are encouraged initially to write in the media domain. When they are taught how to use Microsoft Word, they are encouraged to use it like a desktop publishing (DTP) application – make the text sparkly, change its colour, make it bigger. They told to create posters and flyers. They are not taught how to use Word’s styles. Mark states this wasn’t always the case: > “Desktop publishing was revolutionary in its day because it combines three jobs into one, and eliminating communication overhead between writers, designers, and typesetters. This eliminated the communication overhead, but it made the writer’s job more complex.” ### Rhetoric The book looks at rhetoric and the process of writing, the places where rhetorical decisions appear. Rhetoric is essentially the study of what you say, and how you say it. In this book, Mark looked at rhetoric in the sense what you say – the structuring and organising content. He didn’t look at the eloquence of language – how you say it. Rhetoric is very important in writing. At Cherryleaf, when we improve company policies and procedures, a lot of what we do at is define and create a rhetorical structure. Each procedure states who it affects, what they must do, when they must do it, who is the “owner” of the procedure etc. We have just finished a writing project for an API documentation portal. We documented seven APIs, and made sure the documentation for each API had the same topics, in the same order. Again, we created a rhetorical structure. ## Why adopt a subject domain approach to writing? The core message of the book is that writers should be writing in the subject domain. > “Why should the author have to deal with things like conrefs and maprefs, which have nothing to do with the subject they are writing about?” Essentially, you are writing content like it is data. The basic message is you can: - Use software (algorithms) to process the content - filter content - re-present it - Reduce the complexity for the writer, so they can focus on writing. The book looks at the benefits of writing in the subject domain in depth. There are probably over 100 pages on how it affects: content management, collaborative writing, avoiding duplication, presenting tables, metadata, terminology, reuse, computer generated content, merging and extracting content, linking, filtering content, and more. ## Structured writing languages The book looks at pros and cons of different structured writing languages such as DITA, DocBook, Markdown, ReST and AsciiDoc. > “The vast majority of structured writing today is done in XML using a structured XML editor which presents a pseudo-WYSIWYG graphical editing environment to the writer. This is inherently a document-domain writing environment. It has many problems even for working in the document domain, but it is even more difficult to work in when writing in the subject domain. > > Many people today prefer to work in lightweight markup languages such as MarkDown which you can create easily using a simple text editor. However, all current lightweight markup languages are simple document domain languages.” The differences are shown in this diagram: ### SAM In the book, mark proposes a new markup a language, to make writing in the subject domain easy for writers. [SAM](https://mbakeranalecta.github.io/sam/) (Semantic Authoring Markup) is an extensible markup language with syntax similar to Markdown but semantic capability similar to XML. > *“SAM is designed to make the structure of structured documents clear and explicit to the writer, while also making them simple and straightforward to type.”* > “SAM is not intended to completely replace XML, which is more general than SAM and works fine for most of the things it is used for. SAM is intended as a front-end authoring language for structured writing systems that would still use XML internally.” So what does SAM look like? It looks like this: ``` recipe: Feelgood flapjacks introduction: These healthier oat bars use bananas and apple to bind the mixture, so you can cut down on the fat and sugar. This is a classic {British} (country) recipe. ingredients:: ingredient, quantity, type, alternative butter, 50g peanut butter, 2 tbsp, smooth honey, 3 tbsp, runny, maple syrup bananas, 2, ripe and mashed apple, 1, peeled and grated rolled oats, 250g dried apricot, 85g, chopped raisin, 100g mixed seed, 85g preparation: 1. Heat oven to 160C/140C fan/gas mark 3. 2. Grease and line a 20cm square tin with baking parchment. 3. Heat the butter, peanut butter and honey or maple syrup in a small pan until melted. 4. Add the mashed banana, apple and 100ml hot water, and mix to combine. 5. Tip the oats, the dried fruit and the seeds into a large bowl. 6. Pour in the combined banana and apple and stir until everything is coated by the wet mixture. 7. Tip into the cake tin and level the surface. 8. Bake for 55 mins until golden. 9. Leave to cool in the tin. 10. Cut into 12 pieces to serve or store in an airtight container in the fridge. prep-time: 10 minutes serves: 12 nutrition: serving: 1 flapjack calories: 218 kcal total-fat: 8 g saturated-fat: 3 g salt: 1 mg protein: 6 g total-carbohydrate: 29 g dietary-fiber: 4 g sugar: 17 g protein: 6 g ``` All the media, document and management domain information is stored outside of this document. This means we could use an algorithm to: - Change “fibre” to “fiber”, depending on the reader’s location. - Include it in a book of British recipes. - Include it in a book for meals with fewer than 10 grams of fat. - Change grams to the imperial measures used in the USA (which we believe are knuts, sickles and galleons), for the US market. ## Managing documentation The book also looks at the problems with using a “block and map” approach to documentation (like you have with DITA) and a conditional text approach (like you have with Flare and RoboHelp). Mark proposes an alternative, bottom-up information architecture, which he calls SPFE. SPFE works by automatic collection and linking of content based on metadata, rather than using a top down approach of using tables of content or DITA maps. ### Structured writing and “Every Page is Page One” He connects SAM and SPFE to the “[Every Page is Page One](https://everypageispageone.com/the-book/) ” (EPPO) philosophy that Mark popularised a few years ago. EPPO is an approach to information design which Mark calls “bottom-up information architecture”. It is based on the users finding content mainly by search engines. This can throw the reader into any page in a content set (which means every page is page one in the reader’s journey). It can be their final destination, or it can direct them (via hyperlinks) on to other topics they may need. Wikipedia is the classic example of a bottom-up information architecture. However, sites like Wikipedia require a lot of effort to create and manage the links. The book argues that to do “Every Page is Page One” efficiently, you need to adopt SAM and SPFE. ## Criticisms We liked this book. But… - If you like the approach put forward in the book, and you want to adopt them, you’re likely to hit a snag. SAM is a work in progress. To convert your subject domain content into content for users, you’ll need to be comfortable using scripts from a command line interface. - This approach reminded us of the Headless CMS systems that are emerging, where content is stored as data (in this case as JSON objects). At this stage, [Gatsby with Strapi](https://blog.strapi.io/building-a-static-website-using-gatsby-and-strapi/) , or [Sanity](https://medium.com/buro-int/headless-cms-for-a-printed-pizza-book-54b39827e651) seem more likely to be adopted than SAM. (We’ll be looking at Headless CMSs and Sanity in an upcoming episode of the [Cherryleaf podcast](https://www.cherryleaf.com/podcast/) ). - It’s not clear if SAM supports auto generated numbered lists. - There’s no conclusion at the end of the book 🙁 ## Summary This is a useful book if you want to understand why your implementation of DITA isn’t working, and what alternative approaches are available. Equally, if you want a better alternative to Word or a Help Authoring Tool. We’ll finish with the last paragraph from the book: > “Getting there may require your team to learn new skills, or it may require you to bring in staff with the needed skills. Don’t regard bringing in those skills as a downside of structured writing. Instead, look at it as a method to better handle the complexity of content creation.” ## What do you think? Share your thoughts in the comments section below ### Share this: - [Share on Facebook (Opens in new window) Facebook](https://www.cherryleaf.com/2018/11/review-of-structured-writing-rhetoric-and-process/?share=facebook) - [Share on LinkedIn (Opens in new window) LinkedIn](https://www.cherryleaf.com/2018/11/review-of-structured-writing-rhetoric-and-process/?share=linkedin) - [Share on WhatsApp (Opens in new window) WhatsApp](https://www.cherryleaf.com/2018/11/review-of-structured-writing-rhetoric-and-process/?share=jetpack-whatsapp) - [Share on Bluesky (Opens in new window) Bluesky](https://www.cherryleaf.com/2018/11/review-of-structured-writing-rhetoric-and-process/?share=bluesky) - ### *Related* ### 3 Comments Every first instance of an initialism should be explained. You’ve not explained what SPFE stands for, which is interesting considering it’s arguably one of the author’s primary proposals. The name SPFE is an acronym for the four layers of the SPFE architecture: Synthesis, Presentation, Formatting, and Encoding. [https://spfe.info/](https://spfe.info/) Asciidoc is essentially a lightweight DocBook, and has a lot more in common with its XML parentage than with Markdown. The most customizable PDF toolchains for Asciidoc, to use one example, are (or have been, for a long time) DocBook-based, which illustrates this transparency. The Asciidoc WG also considers DocBook round tripping to be a core function of the language. ### Leave a Reply[Cancel reply](/2018/11/review-of-structured-writing-rhetoric-and-process/#respond) This site uses Akismet to reduce spam. [Learn how your comment data is processed.](https://akismet.com/privacy/) #### Previous post [Announcing the Mathspeak project: Helping non-native speakers succeed at maths](https://www.cherryleaf.com/2018/10/announcing-the-mathspeak-project-helping-non-native-speakers-succeed-at-maths/) #### Next post [Keeping focus when implementing a digital strategy](https://www.cherryleaf.com/2018/11/keeping-focus-when-implementing-a-digital-strategy/) #### Browse posts by month Browse posts by month Select Month October 2026 (3) September 2026 (12) August 2026 (8) July 2026 (7) June 2026 (14) May 2026 (8) April 2026 (6) March 2026 (14) February 2026 (9) January 2026 (9) December 2025 (7) November 2025 (9) October 2025 (10) September 2025 (7) August 2025 (6) July 2025 (1) June 2025 (3) May 2025 (2) April 2025 (5) March 2025 (3) February 2025 (3) January 2025 (2) November 2024 (8) October 2024 (3) September 2024 (2) August 2024 (3) July 2024 (4) June 2024 (1) May 2024 (2) April 2024 (4) March 2024 (1) February 2024 (2) January 2024 (1) December 2023 (2) November 2023 (9) October 2023 (8) September 2023 (5) August 2023 (3) July 2023 (1) June 2023 (1) May 2023 (2) April 2023 (3) March 2023 (2) January 2023 (2) December 2022 (4) November 2022 (1) October 2022 (1) September 2022 (1) August 2022 (1) July 2022 (1) June 2022 (1) May 2022 (2) April 2022 (1) March 2022 (1) February 2022 (1) January 2022 (2) December 2021 (1) November 2021 (2) October 2021 (1) August 2021 (1) July 2021 (2) June 2021 (3) May 2021 (5) April 2021 (3) March 2021 (3) February 2021 (1) January 2021 (2) December 2020 (4) November 2020 (4) August 2020 (3) February 2020 (3) January 2020 (1) November 2019 (3) October 2019 (1) September 2019 (1) August 2019 (3) July 2019 (2) June 2019 (3) May 2019 (4) April 2019 (1) November 2018 (2) October 2018 (1) July 2018 (2) June 2018 (4) May 2018 (2) April 2018 (3) March 2018 (4) February 2018 (2) January 2018 (3) December 2017 (2) October 2017 (3) September 2017 (1) August 2017 (3) July 2017 (2) June 2017 (7) May 2017 (4) April 2017 (5) March 2017 (1) February 2017 (7) January 2017 (1) December 2016 (3) November 2016 (4) October 2016 (1) September 2016 (5) July 2016 (1) June 2016 (3) May 2016 (1) April 2016 (2) February 2016 (2) January 2016 (5) December 2015 (1) November 2015 (4) October 2015 (2) August 2015 (1) July 2015 (1) June 2015 (2) May 2015 (3) February 2015 (2) January 2015 (6) December 2014 (1) October 2014 (1) September 2014 (4) June 2014 (4) May 2014 (1) April 2014 (2) March 2014 (3) February 2014 (4) January 2014 (4) November 2013 (2) October 2013 (5) September 2013 (3) July 2013 (3) June 2013 (11) May 2013 (4) April 2013 (6) March 2013 (7) February 2013 (4) January 2013 (4) December 2012 (9) November 2012 (23) October 2012 (14) September 2012 (8) August 2012 (4) July 2012 (12) June 2012 (12) May 2012 (10) April 2012 (8) March 2012 (12) February 2012 (3) January 2012 (6) December 2011 (2) October 2011 (3) August 2011 (1) June 2011 (5) May 2011 (2) April 2011 (1) January 2011 (1) December 2010 (1) November 2010 (3) October 2010 (4) September 2010 (8) August 2010 (5) May 2010 (2) April 2010 (3) March 2010 (3) February 2010 (2) January 2010 (3) December 2009 (2) November 2009 (6) September 2009 (1) July 2009 (6) June 2009 (7) April 2009 (8) March 2009 (3) February 2009 (3) January 2009 (3) December 2008 (1) November 2008 (3) October 2008 (3) September 2008 (4) August 2008 (1) July 2008 (3) June 2008 (5) May 2008 (2) April 2008 (2) March 2008 (3) February 2008 (2) January 2008 (1) November 2007 (3) October 2007 (2) September 2007 (1) July 2007 (3) November 2006 (1) October 2006 (2) September 2006 (3) August 2006 (1) April 2006 (1) March 2006 (3) #### Browse posts by category