guest words

Connecting the dots between technical documentation and product marketing content In this article, you will learn more about what technical content writing and marketing content writing is all about and what is it not about in today's market trends. You will see how technical content serves as your product marketing weapon. We will also discuss is it good to consider merging technical and marketing content to one content accessible to customers.   Please reach out to me on sadhana.technicalwriter@gmail.com. While we pitch into the discussion of how technical documentation is your company's secret marketing weapon, let us understand in the current industry trends, what technical content is all about and what is it not about. What technical content is about? Technical content focuses on providing useful information about how to use the product, what's new, use case driven, and how the product addresses user's pain points. Technical content is no more about: Restricted access and made available only after product purchase. A step-by-step instruction to complete a straight forward workflow. Traditional documentation where the goal is to make the product usage simple. Limited to customer Administrator's reference. From decades, technical documentation remained as content that is accessible to customers after product purchase. While marketing content is published and available to customers right from product pre-launch phase to ready to go live. However, over the years this tradition is changing. Technical documentation is becoming the key content that customers are referring to prior purchasing of the product. The trend of the technical document being limited as PDF format and with restricted access is changing. Technical materials are made available in HTML form and on all platforms for ease of access. Seeing from the content marketing view, customers are no more relying on marketing materials as the reference before pre-purchase but are more interested to check out the product technical documentation. Why technical documentation serves as marketing weapon? Great technical documentation reflects the quality of your company's technical support. If the documentation is good, then customer experience is most likely to be positive. This encourages the customer to purchase the product. Technical documentation seems more trustable by customers than marketing materials, often as a result of over-promising marketing messages. On the other hand, technical documentation is straight forward and contains information about marketing content does not tell you how to setup and how it works. Customers are using documentation to do their primary research about the product before purchase. Documentation is becoming a critical aspect of pre-purchase research. Documentation includes details of warnings, legal disclaimers which give customers insight about how the product fits in for their business, view about complexity, scalability, and how the company provides support services to them. When your focus is on delivering technical content that addresses customer's needs, pain points, and how the product adds value to their business, it is more likely that customers are interested in buying your product. Ideally, technical content is getting customers to buy the product, thus serving as a marketing weapon. How to improve attention and importance for technical documentation the same as marketing materials Technical content is your product's marketing weapon, it becomes important to deliver product documentation that is not only of high quality but also that makes the content visually delightful. Few of the key points to consider improving technical documentation in terms of marketing material are: Improve the layout, pay attention to look and make it attractive. Make technical documentation available as HTML and designed to access over tablets and mobile devices rather than limiting to PDF format. Make use of SEO, similar keywords to what is used in the marketing materials. Take it to YouTube. You see marketing videos made available on YouTube, to ensure that documentation responses to this trend by creating " how to & quot; instructional videos or replace content with videos wherever possible and make it available on YouTube as well. Use a conversational tone. This makes documentation more user-friendly and easier to translate to other languages. Should companies combine marketing and technical content together? While we figure out whether to combine marketing content and technical documentation, let us understand in the current industry trends, what content marketing is all about and what is it not about. What content marketing is about? Content marketing focuses on providing useful information that addresses user pain points. Content marketing is no more about: What or how the company is doing with the new product release. How the new product is doing in the market. A traditional marketing content where the goal is to get the customer buy the product. Limited to product offerings or sales pitch reference document. Why companies must consider combining marketing and technical content? In today's trends, marketing content is focusing on addressing user pain points which is what a technical documentation does. However, marketing content lacks details about how to setup the product, how the product works, and how the product fits in for the customer's business that is addressed in the technical content. Customers are turning towards technical content instead of marketing materials as a pre-purchase research document. Off likely, there is a fewer audience for marketing content and more focus is on technical content in the current trends. Also, we see that technical content is eventually becoming a marketing weapon. Considering these factors, it is ideal to offer customers with combined technical and marketing content and with focus on delivering content that the customer is looking for in the documentation. The content delivered must help customers as a pre-purchase guide as well as technical details about how to install, use, addresses business needs, and support materials. Prioritize delivery of the content in timelines with product release and marketing timelines and host it in the location that is easily accessible for customers. Importantly, the merge of marketing content and technical documentation achieves uniformity in the content. The documents appear as if they are all generated from a single source. With a lot of focus over the years on unified customer journey, it becomes very important

WHAT IS MARKDOWN? In India Markdown entered in the life of technical writers quite recently precisely after startup culture. Also, the popularity of GitHub and Stack Overflow add to its boom. Still, job opening with Markup requirement is less, but Information Developers Foundation decided to give it space in our next generation Technical Communication Curriculum. If you are using Markdown for technical documentation, kindly let us know. Here we go: Markdown is a lightweight mark up the language with simple text formatting syntax. Father of Markdown is John Gruber. Example of few more lightweight markup language Markdown BBCode Textile Wiki So what, What is for technical writers? Can technical writers use markdown to create user documents or developers documents? What is the learning curve? My company doesn't have the budget to procure the new license for technical documentation team. Hold on: You will find your answer in this post. Let us first understand technically why this is picking up why it is desirable- Capacity to plain text to HTML and that too without any knowledge of HTML and it is FREE :-) It is suitable for organized pieces of content in the web that smoothly converts to clean and structured HTML. It is designed with the explicit intention to be easily readable. The traditional writing user interfaces cause interruptions in the flow of thought process whenever a user has to pause and click their mouse or use complex short-cut keys for writing. Therefore, the advanced writers find it very convenient to apply rich document formatting on the fly seamlessly. What is the ideal condition to use Markdown? Many organization now claim the use of markdown for all kind of documentation. Markdown is extensively used by GitHub and Stack Overflow making it darling of developers. If you are a developer, you cannot ignore Markdown. I being a traditional technical communicator have a different opinion. I may be wrong. Consider using Markdown: When you are writing for software, I mean to say you will not end up writing thousands of page with hundreds of images. Localization is not on your card. You are working in the agile environment. Print documents or single sourcing is not your requirement. Content reusability is not a priority. Low on budget. In fact zero budget for tools. If you have anything to import from classical authoring tools. This not tool is not for you. In nutshell, it is a very good bet for startups. MARKDOWN FORMATTING SYNTAX The basics syntax of Markdown is pretty simple. Here are some of the basic elements often used: HEADINGS Use any line as a heading by prefixing with the # symbol Heading 1 is prefixed with one # Heading 2 is prefixed with two ## Similarly, Heading 3 with ### For example: # Heading 1 HEADING 1 For ## Heading 2 HEADING 2 TEXT Emphasize texts by using italics, bold or both italics and bold easily, with the help of either asterisks or underscores. A text can be wrapped up in a single asterisk (*) to make it italics. It can be wrapped with a double asterisk ( ** ) to make it bold. Or triple asterisk ( *** ) to make it bold and italics. For italics *italics* For bold **bold** For bold and italics ***bold and italics*** LINKS There are two types of links : Inline links Reference links INLINE LINKS Wrap the text to be linked, in a square bracket ’ [ ] ’ , followed by the URL to be linked to in parenthesis ’ ( ) ’to add a link. i,e [text] followed by (URL) [Markdown official website](https://daringfireball.net/projects/markdown) REFERENCE LINKS As the name implies, the reference link is a reference to another place in the document. It is written as [ text ][ xyz ] . Now you can define the link anywhere in the document [ xyz ]: URL [text][xyz] [xyz]: URL IMAGES The syntax of inserting an image is similar to that of links. The only difference is that you need to prefix an exclamation mark ’ ! ’ in front of text wrapped in square bracket ’ [ ] ’ followed by the URL in parenthesis ’ ( ) ’ . i.e ![ text ] followed by (URL of image).  For a reference image follow the same pattern as reference links. Images can be inserted in a similar way as reference links by defining it later. ![text][id] [id]: URL LISTS There is two type of lists: Unordered list Ordered list UNORDERED LIST To create an unordered bullet list, you need to preface each item in the list with an asterisk ( * ) or (+) or (-). For example: * Butter * Bread * Apples * Eggs The Markdown list would be represented by the following bullet points: Butter Bread Apples Eggs You can also create nested lists by putting four spaces, and it will be nested under the line above. ORDERED LIST For an ordered list, prefix a number followed by a dot and space, before the text. Butter Bread Apples Eggs MANUAL LINE BREAK End a line with two or more spaces. HORIZONTAL RULES Three or more dashes ( – ) or asterisks ( * ) is used to throw-down a quick divider in your article to denote a visual separation between different sections of text. --- * * * - - - - BLOCKQUOTES Markdown’s blockquote syntax is useful when a sentence or a paragraph taken from another source, calls to draw special attention to the reader. To create a blockquote, you have to preface a line with the “greater than” sign ( > ). For example > Peace begins with a smile. Peace begins with a smile. CODE SNIPPETS If you’re a technical writer, you may want to use example snippets of code to explain your readers a particular syntax. Use a single back-tick ( ` ) around a word in a sentence, to show a quick code snippet. Example of an inline code snippet. Similarly, to create code blocks place triple back-ticks ( “` ) before and after the code block. A blank line before and after code blocks makes the raw formatting easier to read. For Example: int main(int) { std::cout << "Hello World" << std::endl; return 0; } AUTOMATIC LINKS https://gotechwriter.wordpress.com https://gotechwriter.wordpress.com ESCAPING Escaping Markdown characters

Agile technical writer Agilism can be described as a concept, a doctrine, a philosophy, based on tenets of Agile Manifesto and Agile principles, as applied to Software Product Development. It is interesting to share that Agile principle when applied to any product development process, enhance the rate of product delivery in general, with simple, working prototypes produced early in the project lifecycle. Early prototypes ensure customer satisfaction and encourage them to actively participate in shaping the product according to need and required functionality. It provides with the opportunity to give directions, create changes according to need and ultimately, help the team to develop a product with value and maximum Return on Investment (ROI). Customer feedback helps the team to iterate, re-iterate the product in a continuous manner and help in fast, simple, and better product delivery. Cross-functional and self-organizing teams work best in this environment. Agile principles can be applied similarly to documentation product delivery, as well. Effective agile documentation is a balancing act, for an Agile document developer. The goal is to write just enough documentation, just in time and just for the right audience. Application of Agile, to product documentation in general, while working on an Agile project enabled me, to align my documentation, with the developing software product. I worked with a truly Agile team, who were fast enough in product delivery, after each iteration. My journey from a Technical Writer to an Agile Technical Writer was really hard and exciting. To catch-up with such a team and simultaneously document the features of working financial product, it was necessary to know their working styles. Application of Shu Ha Ri model – the Japanese Martial art concept of training and learning, came handy to me in Agile documentation journey. Therefore, I began to learn the basics. Enrolled myself in Agile awareness and training program in the organisation and thus started my Agile journey. This model describes stages of learning from beginner to level of mastery, this concept helped me, in learning Agile principles and gaining the skills, required to create, agile documentation and later apply the same principles to my documentation style. According to this age-old Japanese Martial Art concept: Shu– Learn and then perform actions to become the showstopper and role model, for others to follow. Ha– Innovate new styles of product deliveries, improvise, and apply Agile rules. Ri– Transcend finally with your unique style to a different level and establish your own niche. Agility is part of my daily routine now. I find myself somewhere between Shu – Ha stages where I have learned the principles of agility, and strictly and honestly following them in my style of agile documentation, with spikes, as and when required. This enabled me to gain customer confidence and produce faster, simpler, and better documentation with maximum Return on Investment (ROI) value! Following Shu Ha Ri model may also help and envision the newcomers and future aspirants of technical writing field, in gradually setting up the stage for, creating an agile mindset and equally agile working environment. Technical communication community, practitioners, as well as the young aspirants, may gear up, learn and apply the Agile methodologies in their Technical Communication during project and product documentation. They can be encouraged to learn the need of continuous iteration, through feedback and fast document delivery, according to customer requirements. Produce incremental quality documents, with minimum or no defects. This will enable them to write just enough and just required, precise documents, which are light, simple, and easy to refactor. Technical Writers and aspiring writers will get to know the nuances of writing in Agile which they would like to remember, innovate on their own, improvise, and apply to their styles of writing. They can learn to be on edge all the time, catch-up fast with changing the environment, reap the benefits of learning new tools and technologies fast, to mold themselves with emerging technologies, and adjust to the changing requirements frequently. All this could be achieved by being agile enough to pick up new techniques and methodologies and leverage them to enjoy maximum benefit. Shu Ha Ri model can enhance the quest for learning Agile methodologies, create a mindset for faster and simpler documentation and improvise further for the advantage of a technical writing community. This model urges the followers, to take a plunge in the lake of agility, hone the skill and gradually apply it to their document deliveries, while adding a dash of technology and creativity, increase expertise to an extent where they become the trailblazers, on the path of documentation. Such an environment and mindset can be created by self-motivated individuals, who really want to make difference in smoother, faster product delivery and contribute in agile transformation. They should follow Agilism, follow tenets of Agile methodologies while learning through Shu- Ha- Ri model and walk through the path of Agile learning and gain mastery in Agile documentation! If you want to learn and understand the principals of agility in documentation join Information Developers Foundation Certified Agile Technical Communication.   Author Biography Shikha Saxena Shikha Saxena is a Senior Technical Writer in HSBC Technology, Pune, India. She is actively involved in learning and applying Agile methodologies in product and business architectural documentation in financial domain. She is an active blogger on organizational intranet. Managed web content writing, editing, and publication of the same.She was a lecturer, teacher, researcher, and mentor to Science (Biochemistry) and Engineering (Biotechnology) Graduates and Post Graduates of Uttar Pradesh Technical University (UPTU), in NCR, New Delhi, India, before her global career as a Software Engineer/Technical Writer (2009).  She envisions the community in multiple ways and contributes towards making society, vibrating and lively place!

In an initiative to encourage ADID Alumni and other technical writers to share technical writing knowledge, ADID invited Neha Srivastava to share her understanding on the documentation development life cycle and she comes up with well-knit and researched post. You can write to her or post a comment to ask anything dropping from your mind on DDLC. Introduction to Document Development Life Cycle The Document Development Life Cycle (DDLC) is the process of developing documents. It is necessary to follow DDLC to enhance the quality and optimize timely delivery of the document. The Document Development Life Cycle is mainly comprised of steps which are given below, it can vary company or project-wise also:            Requirement Analysis            Designing            Developing the Content            Editing/ Proofreading            Publishing            Maintenance  Requirement Analysis During the Requirement Analysis process we gather the information of the product from SMEs, available documents, online search etc. We analyze the criteria of producing the product according to the audience. In Audience analysis, we analyze who will use this product, what is the need of creating the product, and measures of skill and expertise of the audience etc. We also figure out what tools we are going to use like RoboHelp, Framemaker etc.  By understanding the product requirement, we can easily estimate the time, resources and cost of the product. Designing In Designing phase, we design the document we create templates, master page etc.We take approval of design like fonts size and style, list, table, numbering and look and feel approval is taken from concern person.  Developing the Content We develop the content according to the product features and requirement. We analyze the product, run the product and write the draft according to the product. We create user manual, user guide, reports, and online help etc. We add a title, copyright, content, index, glossary, and appendix etc in the manual.This is actual content development phase.  Editing/ Proofreading Editing is the process in which we test the creating project according to the requirement, and product features. We check the first draft through Technical Writer-editor, peer review or the technical review etc. In this phase, we check the technical part, grammar mistakes, figures, and format etc. Proofreading is the final testing of the project by checking proper layout, style and grammar mistakes etc. In this phase, we check the draft entirely. Our main purpose is to remove the bug from the draft, so that document is clear and understandable.To read more on proofreading click here.  Publishing In this phase, we publish the document as online help, and print document etc. Print documents are the hard copy in which all the content may be in long sentences or paragraph, and screenshots. In online help, we add hyperlinks, and content is in short sentences. These documents are useful to end users to determine the exact use of the product.  Maintenance Maintenance is the process in which we add updates, create versions after modification in the project. When a new product comes into the market, the user manual is updated according to the added new feature. Companies also spend cost in creating Support Centers for enhancing user satisfaction.

Sasmita Panda wrote this guest post.She is a seasoned Information Developer, Content writer, and blogger. I invited her to share her experience on the primary skills required by information developers and she come up with a well knit blog for you. Read more blogs of Sasmita on TWIN  What are the qualities of a good technical writer? Mastering over the language or strong technical skills? The debate is constantly on. As per my experience, language is important, but it’s your acumen in technical skills which will take you higher in the long run. Strong writing skills along with deeper technical knowledge are always considered as added advantage. Understanding a product/application and documenting about it is what every technical writer does, but knowing about how to structure and present the information to various types of end-users is definitely a valuable skill. There are technical writers who are good in writing skills but poor in technical skills and vice verse. You can always work on the skills you lack, but I believe that honing technical skills takes longer time as compared to the writing skills. You don’t have to stupendous in your writing skills to be a good technical writer, but expertise in technical skills is a must especially if you want to grow in your career as a technical writer. Proficiency in technical skills has a growing demand in many industries these days. Knowledge of DITA, API Documentation or software programming can fetch you a better package than many of your experienced peers. So if you want to grow and make money as a technical writer, the choice is obvious- sharpen your technical skills. Related PostTwitter Vs FacebookBefore you foray into technical writingAfter you foray into technical writingJobsWhy Should you love book Please take out few minutes to write your view on Language Vs Technical Skills.