Talk:Technical writing/Requirements analysis

TWFred 15:00, 30 July 2007 (UTC) What are the user's goals?

Learn about technical writing so they can change jobs? So they can make more money? So they can be a better programmer, analyst, translator, teacher?TWFred 15:00, 30 July 2007 (UTC)

Tanya: you mean personas' goals?

For example, Joe Smith is a bit bored working as a teacher and wants to become a technical writer.

Sandra Jones (personal assistant) just wants to read several topics on TW (without going into details) because she is dealing now with technical documentation and this is a new area for her.

Wing Lee (engineer) must write a lot of technical documents by himself. So, he would like to know more about TW.

There may be other people, such as managers who deal with documentation projects and want to improve the whole process, translators who work with technical documents and needs information on TW, and technical writers themselves who would like to improve their skills.

Tanya: I began to put some requirements (without formulating them) under these groups. After we'll think out all the needed requirements, we can begin to describe them properly.

I won't have any time today at all (even for 5-10 min). So, please help me.

RobA: One question, they want to learn about technical writing on the wiki or they want to learn technical writing on Fred's course? (If this is actually a relevant question..?) :)

Snooze: I finally managed to sign in !!!!

RobA: Cool, I put some of the what looked to me 'easy' requirements on. Feel free to mess around.

Rom & Wlodek: Talk face to face is sometimes better.

Martin: I've got a question about SF 050. Is it reasonable to define such a high resolution of pictures (at least 1024x768)?. Let us think about a situation we need to show how a small icon seems. Shall we upload a 100K file with a great resolution for this reason? Moreover, sometimes it occurs, that jpegs in lower resolution and better quality seem better than jpegs in a high resolution, but high compression.

Roba: To Martin, I meant so that the picture can be viewed on monitors with this resolution or above, perhaps the wording needs changed. I only say this because we had problems fitting diagrams on the last exercise (NGN structure) onto the OHP Fred's laptop was connected to and it was basically a monitor resolution issue.

Martin: To RobA: So, if I understood correctly - the pictures must be loaded in lower resolution than 1024x768 in order they could be displayed on one display area in cases when the software does not automatically lower the resolution in order to fit display's capabilities...

RobA: to Martin, yep, that's about right! :) Do you think it should be changed to your definition then? "Images etc. must be not larger than 1024x etc....." Also to Rom: The contents parts don't seem to be requirements to me, more like definitions. It should be about what the wiki should "have", such as 'The wiki must contain a section on XML' or somesuch... anyway....

BartJTW: To Rob, Martin: upload an image and then use HTMLS: <image= width= height>  :)

Martin: To RobA, BartJTW: Thanks for comments. I am thinking whether to define the maximal resolution or not. Definitely, the width and height of the picture shall be defined in HTML, but pictures in big resolution occupy a lot of place at the server without any reason...

Rob: To Bart and Martin, That's still okay cos it doesn't change the requirement.... hehe!

Martin: To Rob: I am afraid these are two different ways how to achieve the goal - to define a resolution in which pictures can be uploaded (spares place at the server) or to define in which resolution the pictures are displayed :)

Martin: I just have another comment to A010. Being available anytime anywhere to anyone is not reachable. The reliability of the hosting server shall be defined as well.

Rob: remember this is a requirement document, not a design doc or an implementation doc. It doesn't matter "how" the requirement is solved just that it is and as long as the solution is testable against the requirement, the requirement is valid... :)

Tanya: I can't understand C 020 requirement. It's not a requirement in fact, just some description.

Martin: Sure I remember this is a requirement document. This is why I consider it reasonable to set the requirement in that way the place at the server was saved. For this reason I suggest to define the maximal resolution...

Tanya: I'll delete this: The Extensible Markup Language is one of the most used tools in technical writing (CMS). XML gives the possibility to better organize (consistent) and labeled the obtained information and allows easier documents transportability and management OK?

Sasha: LC 020: Which style guide we are going to use? Any suggestions? What about OSS/BSS Publications Style Guide? ;o)
Also, I've added the User of the Product section. I think it's quite important to specify who is our end-user both on the discussion page and in the requirement specification.

Tanya: I agree that it's important to specify the user. But I think we shouldn't put it as a requirement to our wiki. I suggest to create some short description of the users before the requirements chapters.

Rom to RobA: Hum!:-) nothing against your opinion. Sorry, but your contribution about XML seems to me a bit strange: <<It should be about what the wiki should "have", such as 'The wiki must contain a section on XML' or somesuch... anyway....>>. Please could you explain what you meant by this?

Rom to Tanya: (about C20) I think that is OK. No need to have more details.

Rom: (about SF 050: <images: size, location, captions>) So far, according to my experience of working on wiki pages, I can say that the image size varies according to the computer machine display settings (exercise on NGN). Sometimes the image may be displayed very well-sometimes not. The solution I've found, was just to place the picture as a thumb. Then later by clicking on this picture, wiki offers the possibility to display the picture according to the HD size. So I am not quite sure if here we may set a fix size to follow.

Wlodek: (about SF 050: <images: size, location, captions>) I wonder if that`s possible to use relative size of the image so that its width and height is always given in percents - %. That way it always takes the same space on the display in browser window and we do not need to worry it is to big or to little. The quality of the picture, its details etc. depend on its resolution. It is another thing 2 think.

Tanyato Rom: What is OK with C20? I deleted the whole thing. We need to formulate which XML issues we want to include in our wiki.

Rom: to Tanya(C 020) I think that this is from you? No? Tanya: I'll delete this: The Extensible Markup Language is one of the most used tools in technical writing (CMS). XML gives the possibility to better organize (consistent) and labeled the obtained information and allows easier documents transportability and management OK?. And my answer came from that.

Rob: I know it may sound pedantic but on the interactivity part, the requirement is the user's requirement of the wiki. So perhaps it should be worded something like 'for the user to access discussion the wiki must allow logging on' or something like that?

Tanya: Yes, I agree with Rob. We spoke about this in our lesson. Fred, what do you think about it? For users, we can write 'the wiki must allow', but we how should we write for our admin? :)

--BartJuniorTW 12:36, 2 August 2007 (UTC) >>>> Wlodek: (about SF 050: <images: size, location, captions>) I wonder if that`s possible to use relative size of the image so that its width and height is always given in percents - %. That way it always takes the same space on the display in browser window and we do not need to worry it is to big or to little.
In HTML it is possible <img src=blah.blah height=50% width=50%>

--BartJuniorTW 12:42, 2 August 2007 (UTC) >>>> Tanya: ... but we how should we write for our admin? :) >>> Write: Our Mr. Master Admin must... :)

Jana: About images: I suggest to use only framing.

Admin

Tanya: Yes, poor admin doesn't have to be responsible for everything. But he/she must control the whole stuff somehow. Why else do we allow him/her to block an account, for instance?

Fred's comments

TWFred 08:04, 2 August 2007 (UTC) (About users)
Is this true? What about Joe? Is Joe an improper persona? Would the course be better if it were more geared to Pavel Novak, a new project manager here in Prague? That would go nicely with Patricia Fong, a 23 year old who just got hired as a business analyst in Hong Kong...hmmm.

As Bart notes at the bottom, think about your persona.

TWFred 08:04, 2 August 2007 (UTC):
Remember, if we're using Joe, his goal is to find out if technical writing is a wise career. If he is convinced that it is at least worth time and effort to investigate, he'll perform some (probably not all) exercises. He would want to know if there is any certification online (that doesn't cost a ton of money like the course you'll find in a quick search) (and yes, certification is at this time OUT OF SCOPE for the discussion of the wiki) (and yes, it's bad form to write so many consecutive parenthetical comments, but I'm on vacation, so edit this if you don't like it)

TWFred 08:04, 2 August 2007 (UTC)
Again, crucial to decide who your persona is. Joe's an SME on English. But PMs and business analysts are programming or process/business sector SMEs who are probably NOT English L1 users. Totally different courses are required, where the first explains and gives practice in IT development standards, and the second focuses on English usage and proper wording of various deliverables in the SDLC (which you wouldn't have to cover, just refer to PMI, PMBOK, SEI, and similar resources.)

AlistairReece 08:39, 3 August 2007 (UTC) I would question whether most ESL teachers are really SMEs on the English language - from my experience in Prague and even in Minsk the majority of ESL teachers are taking a couple of years out before going home to resume a career in whatever they studied.

TWFred 08:04, 2 August 2007 (UTC)
If we gear the wiki to ESL teachers, we can use very fancy language. Clearly, however, because of the team making the wiki, it's far better for us to take advantage of our collective linguistic experiences to make the site as international as possible. Since this in no way excludes the Joe's and other ESL teachers, I propose that we do this anyway.

08:09, 2 August 2007 (UTC)
About C 05: What is "complete". How do you test completeness? Maybe, "exercises must be performed using proposed instructions by at least three class participants prior to adding to the wiki?" That would be a lot of trouble and time...Perhaps, "all instructions must include step by step instructions, and a an example that show the completed goals/tasks/outputs of the excercise." I dunno...make it up and be reasonable.

TWFred 08:14, 2 August 2007 (UTC)
Excellent requirements on formatting. Very clear. I might disagree with some, but that's the point. We'd know exactly what to disagree about. Very good job.

But the ugly structure problem is untouched.

First off, order.

What comes first? Tools? SDLC? Career info? Audience Analysis? Writing Rules?

AlistairReece 08:39, 3 August 2007 (UTC) Regarding order. Considering the wiki is aimed at people considering a career in TW, or those just embarking on such a career, the first question they would ask themselve is "am I making/have I made a good decision?", as such career info is the most important information.

Second, what's the structure of the navigation?

Clearly, each page has TOC. How are pages linked together? Previous/Next links? Back to Technical Writing links? If we're deep in a pyramid shaped structure, how do we provide up and down as well as side to side navigation?

AlistairReece 08:39, 3 August 2007 (UTC) I think that at the top of each page a "return to" should be present, while at the bottom "continue to".

--Romeo 06:49, 7 August 2007 (UTC)Something similar was suggested last time at trainings and I think that Alistair's suggestion is OK.

1. I would add to this suggestion a "return to first Main_page" to allow the user to jump directly to the first page(e.g. document having thousands of pages).
2. One more thing could be to insert inside each page a TOC. But here I would be careful- I would just insert a TOC related directly to the section, to which belongs the actual page but NOT the whole document TOC (simplicity and clearness).
3. The navigation Up-Down on the same page may be left (Mouse and keyboard would do the job).
4. One, no less important thing could be to use also what offers the document viewer (browser, MSWord, Adobe ...) as navigation features, up to not have a duplication.

Collaboration tips

Hi there - sorry for jumping in, but the collaboration on this page is quite interesting to see as it unfolds! I thought I might suggest a few things which might be helpful. There is a plus sign (+) at the top of the page which you can use to start a new conversation. It will create a new section on this page which you can edit. In this way, you can have concurrent discussions about different ideas easily. Also, take a look at the page history - if you provide an edit summary while saving your edits, you can keep an active log of why particular changes have been made. Another tip is for signing posts. You can do this by putting --~~~~ immediately after your message. It will create a label just like the one at the end of this message. It makes it easy to contact users directly on their userpages. Finally, if you have additional questions about Wikiversity, or how to use Wikis in general, please feel free to post them to my talk page, or the Wikiversity:Colloquium. There are lots of users around who would be more than willing to help out. Anyway, just to say a few words of greetings - cheers, --HappyCamper 16:17, 1 August 2007 (UTC)

Hey, this stuff really works!!

Following HappyCamper's suggestion.

Please, whoever edits the resource page next, rip out my comments as they are addressed. I really should have put them here. Sorry.

TWFred 08:49, 2 August 2007 (UTC)

Images formatting

Three issues:

Upload size and naming parameters (location would be on wikiversity servers, which require strict copyright laws -- if location other server, brings up whole wiki admin issue and reliability, and access and so on...)

Display parameters including size, dimension, thumnails, frames, and placement (w/wo text)

Labeling/captioning/naming standards

Non-Functional Requirements

I think Martin has raised some non-functional requirements. Make a new section for these.

XML level

Tanya and Rob bring up a good point...

What level of XML doesn't have to be completely decided here. What has been decided is that for User Joe Smith, it would be only an introduction, focused on why it's important to know rather than all the details of transformations and DTDs and FOs and all the other fun tricks we can do with xml. Better to let zvon.org do that.

If the user is more PMs,TWs,BAs, then similarly, we don't have to go into much detail on xml because they already should know something of it. They just want to know the considerations for the primary technical documentation DTDs, DocBook and DITA.

So what's the audience again? TWFred 08:58, 2 August 2007 (UTC)

AlistairReece 09:24, 3 August 2007 (UTC) I bought "Teach yourself XML in 10 minutes" while I was in the States, it looks like a useful guide for someone with no prior knowledge. Will keep you updated about how it works for me.

AlistairReece 09:43, 3 August 2007 (UTC)Thinking more about the persona though I think it is important to introduce XML without going into depth at all. If the persona is someone looking to get into technical writing then they are likely to research such things for themselves. Point them in the right direction should be enough.

Draw table in Wiki

Rom: Due to lack of time I would suggest to colleagues to consult the help on how to draw table on wiki. In case of any problem, we can eventually together figure this out- we are just learning so no matter if we do not understand. We will perform better in the future. Fred: what do you think about this idea? --Romeo 16:09, 2 August 2007 (UTC)

Rom: a possible tip to start .

Rom to Alistair: Hey, I didn't find the table , you were talking about this morning. :-). Please, once you will get back your pc and you will find a bit of your free time, put here a link to that. It may help people learning more about these stuffs. Thanks.--Romeo 07:33, 3 August 2007 (UTC)

80.95.102.226 08:43, 3 August 2007 (UTC) It seems that my old page has been replaced with a different page I made. I will find the code for a table and post it.

--Romeo 10:26, 3 August 2007 (UTC) ok, I understand. :-( Anyway thank You! However I have got myself, a built table on our internal wiki page(Sitronics one), which link has been provided upstairs so anyone, who wants to use it as start up, may do that. The syntax itself is easy- we just have to practice. So to All, feel free to improve the algorithm and add your proper features as you feel it is needed.

You should be able to see that page here 80.95.102.226 08:44, 7 August 2007 (UTC)

Language

Tanya: How to specify the difference between British, American and international English? How shall we check if the requirement on international English (LC 010) is fulfilled?

AlistairReece 09:44, 3 August 2007 (UTC) personally speaking I think that using standard American or British English should be enough to satisfy requirements. The important thing is consistency - sticking with one or other of the standards rather than flitting between the two. Admittedly that is easier said than done.

Found this article with guidelines on Plain English (which may be a better alternative to "international English") AlistairReece 10:46, 3 August 2007 (UTC)

--Romeo 11:00, 3 August 2007 (UTC) I am not quite sure about the following but it seems to me to be a possibility:

1. It should be a hard task to map the difference between these three types of English. Moreover, we do not have only these types of English (e.g. Canadian, Zimbabwean, ... ), so I wanted to ask Fred, why we did not assign the other types!? I would just set up the language used (as you wrote international English) and specify the language rules.

AlistairReece 12:47, 3 August 2007 (UTC) the vast majority of people speaking English use either American or British English, and the differences are not dramatic enough to bother mapping other variants. Ultimately it is irrelevant whether you speak or use British or American English because in this field.

1. To me, what really matters is the type of words used (strong words [sometimes called big words], slang, synonymous, ...).
2. Again to me, in TW (in any language) the words used must be simple and understandable, not only to the native speaker but also to anyone, who is able to read, write and understand this language.

AlistairReece 11:13, 3 August 2007 (UTC) That is the beauty of Plain English --Romeo 10:48, 6 August 2007 (UTC) To Alistair: yep! That is!

Tanya: Good link, Alistair. Thanks. Btw, in our OSS/BSS Publications Style Guide we have British English as a standard.

Wlodek: There is something here: Found Simplified Technical English Perhaps it also could be inspiring to read a little bit.

Personas

As you can see I have created three pages for building personas, I think it would be useful to flesh these guys out seperate from the main requirements analysis page. I will be sorting out some pictures for each of them, give me a few days. AlistairReece 06:48, 6 August 2007 (UTC)

You can find the personas here - please feel free to make changes/suggestions. AlistairReece 07:58, 7 August 2007 (UTC)

Notice concerning course in August

Please note that the lessons will consist of the following subjects this month.

09.08 Introduction to Snap and wiki tables

14.08 Requirements Analysis

16.08 Document conversion process, introduction to Visio and Beyond Compare

21.08 Introduction to SVN

23.08 Introduction to XML

AlistairReece 11:56, 7 August 2007 (UTC)