We write specifications. Part 2. Tools. Wiki - everything is at hand

I continue to talk about the tools with which you can make such a complex and unusual process of writing specifications simple, accessible and even fun (see Part 1. Tools - we start with a simple one ). I have long been thinking about how to adapt for this wiki.
What came of it - read below.

Acknowledgments
At the festival 404 I was very interested in the report of Konstantin Kolomeyts from Yandex on the use of various tools for teamwork . Further discussion and answers to questions in the experts' corner on a cozy sofa turned out to be even more interesting and informative. This was the impetus that tipped the scales from long thoughts to action.

We recall the requirements for tools

Convenience of reading.
It's all simple. All that is needed in order to read the specification is the browser. Skills in the browser probably have all :)
Convenience search.
Find the desired article in our wiki in two ways:
1. Navigation / links. On the sidebar (sidebar), as well as on the first page of the wiki, there are links to all our projects, and on the main page - also to the description of our internal processes.
  On the main page of each project there are links to all (or almost all) articles on this project. This is such a big-big page consisting of links only. They are divided into categories (description of processes, user interface, server-to-server interaction, etc.). There are even references to those specifications that are not yet, but which should be exactly.
2. Search. Now used native search MediaWiki. (There are a lot of ways on the Internet how to fasten one or another advanced search engine. But so far there is enough of a native one in order to find the article you need by one or two keywords.)
History of changes . Built-in tools is enough.
Collaboration . Built-in conflict resolution is enough. While editing a document is not entirely, but a specific section, the chances of creating such a conflict are very small. In our country, this happens no more than once a week.
Convenience of editing
The fun begins. I had a task - to make our colleagues WANTED to use our tool. For this, it is necessary that simple and everyday actions do not require study, but should be done in the usual way. Further study of the toolkit (markup language, any extensions) should bring immediate and tangible benefits - to increase the speed of work or to provide new opportunities.
Below I will talk about how I fought for ease of editing.

Recruiting tools
1) Engine. Mediawiki
Wiki engines a lot. I would not venture to say that one is better than the other. I chose the one that suits us.
First, it is free. Turning to the wiki, I was not 100% sure that this would be the final decision, so I did not want to risk buying any commercial system. Moreover, at that time for me (I exaggerate a little) all the wikis were the same person.
Secondly, the implementation language. PHP / MySQL. We already had such sites, and such specialists, and we were ready, if necessary, to twist-twist something.
Thirdly, a large number of any extensions.
And finally, a big name. I was hoping that this engine would be reliable enough, since it pulls Wikipedia.
')
2) Editor. WikEd + FCKEditor
Of course, I wanted a vizivig. Any new system will be perceived with hostility, if you have to change your habits to work with it. In this case, the habit was working with texts. All were able to work in Word. But I didn’t want to force analysts to learn all the markup languages (albeit very simple, but not needed by them for the performance of their main work). For programmers, I was calm. After html wiki markup is just a fairy tale.

FCKEditor - wysiwyg editor. Looks like a Word (you forgive me for remembering him through the word, but life is such that any IT person can write in Word and, if he is lucky, he can write something else). So, he looks like a Word. Including hotkeys. Convenient to work with tables. It is convenient to make links to other articles - he himself offers a choice of several articles on the entered keyword.
But there are also disadvantages. The main - work with the buffer. He agrees to insert formatted text into the buffer. But from the buffer - figushki. Only plain-text. What a surprise. I cut a paragraph, I want to insert it at the beginning of the document - but no. It is necessary to select and drag with the mouse. I'm not talking about the insert from the Word (and how can we transfer our old specifications?)
The second big minus is that the contents of the templates and syntax extensions are not shown. That is, it is clear that there is some kind of garbage inside. Want to see what - see in a separate window. This is inconvenient because we have a number of sample templates for comments in the text, descriptions of scripts and notes.
Therefore, one editor was not enough for us.

WikEd. Complete opposite. It has advantages where the opponent has minuses. But vice versa.
Minus - it is not quite wysiwyg. This is a wiki markup editor. It shows bold fat and italic italic, but also shows markup. And accordingly, it does not show what our readers will see. It is necessary to press a preview.
Plus is probably the best editor for wiki markup. For those who prefer its vizivigu.
Plus - the ability to insert formatted text from the buffer. In particular - from the Word. With the subsequent conversion to wiki markup.
Minus - it does not work in Internet Explorer. Uncomfortable, but not critical. Analysts master firefox. Worse fans of the Opera. They do not want to switch to firefox.

That's how we live. Two editors. Switch from one to another, depending on the task. The original version of the document is convenient to edit in FCKEditor. In it - to work with tables. Final markup, as well as insert notes, more convenient in WikEd.

3) Export. PDFBook + file completion for upload to Word.
One of the questions in the implementation of the wiki was - how can we coordinate our specifications with the customer? We have a wiki on the intranet, and there are no chances to put it out. Yes, and how can the customer write their comments? Also learn wiki markup? Not an option.
Option - export to some universal format. You will laugh, but it is a Word. PDF can be read, you can print, but the customer will not write anything in it and will not fix it.

PDFBook allows you to save the current page, or so-called binder, to PDF. A binder is a special page that contains links to other pages in the form of a bulleted list. This page will be the content of the future book, and all the listed pages will be included as chapters.

We have slightly modified this extension, and now it can also create Word documents.
We added links to call this extension to the sidebar, and now any page can be saved in a doc or pdf file.

4) Sketches of screen forms. Balsamiq mockup
This is just a miracle. Remarkably simple and cool editor for sketching UI. It sketches, unlike, say, from Visio. The resulting drawing looks like a pencil sketch by hand. And that's the beauty. Drawing in Visio, the sketch looks almost like a real interface, and, willy-nilly, I want to make it “beautiful”. And in Balsamiq Mockup there is no such temptation. The attention of the developer and the customer focuses on the main thing - the overall design of the form, the composition and location of controls. Without being distracted by such insignificant moments as colors, fonts, pixel alignment of elements, and other beauty. Which, as a rule, the style guide is determined by the project.
Another convenience is a large set of building blocks - controls. At the same time, complex controls (for example, a multi-column table or a tree) are not more complicated than simple ones (buttons or labels). Who tried to draw in Vizio a tree, will understand me.
Due to all this, the speed of drawing the interface compared to Visio increases many times.
And finally, the most important plus. This thing integrates nicely with wiki. The editor is an AIR application that runs directly on the wiki page. And the sketch in its format also saves directly to the wiki. The developer’s site offers an option for xWiki. But the easy modification of the file allowed to run it in MediaWiki.
And finally, I must say - this is the only paid extension (of all used by us). But it's worth it.
By the way, there is a desktop version. (Free, only every 5 minutes offers to buy yourself). Our analysts take it with them, going to customers.

5) UML. PlantUML
Using a special syntax, you can “draw” UML diagrams directly in the wiki text. And then, according to this textual description, a picture will be constructed.
```
     <uml>
        Alice -> Bob: Authentication Request
        Bob -> Alice: Authentication Response
     </ uml>
```
All chart types are supported (unlike many other free programs that only know class diagrams and sequences). This, of course, is not a tool for serious UML design, with generating source code. But quite enough to illustrate the design decisions. One picture is worth hundreds of words.
Unexpectedly for me, with the advent of this extension, UML has taken root in our company. Before that, there were attempts to draw different diagrams in the visual. But this was done somehow through force, without pleasure. I think because the visio is too strict and demanding. But PlantUML, on the contrary, forgives a lot, he tries to guess what he meant. And therefore it is a pleasure to work with him. My colleagues as a substitute. Everyone suddenly fell in love with UML, which I am extremely happy about.

6) Syntax coloring. SyntaxHighlight GeSHi
In many specifications, along with diagrams, we immediately throw some code. I want it to look clear and familiar, as in the development environment. The extension for syntax highlighting helps us in this. Included is support for heaps of languages, we do not use all of them. For my beloved Delphi, I twirled the settings a bit to make it look more like an IDE.

findings
When properly configured, the wiki becomes a great tool for writing (storing \ searching \ reading) specifications.
Such a common notepad + pencil in which you can write at any opportunity. So we try to do. You know something - write it faster on the wiki until you forget.

I will not cheat. There are things that are uncomfortable to do, and that you want to improve. Maybe this is the generic flaws of the wiki, and maybe we still just have not found a suitable extension. This article has already come out very long, so I’ll leave the list of our troubles and desires to the next article.

Related Links
- MediaWiki: Silver Bullet or Swiss Knife? - presentation. Same as article
- kolomeetz.ru/blog - many different articles about using a wiki as a corporate knowledge base.

Source: https://habr.com/ru/post/85613/

All Articles

We write specifications. Part 2. Tools. Wiki - everything is at hand

More articles: