Creating efficient documentation based on XML? [modified]
-
Dear members, I have some beginners questions. I'm acting as a SW-architect and I have to create a lot of documentation. I do this with a lot of heterogenous tools: MS-Word, xls, Powerpoint, PDF, HTML, .... Everything is incompatible and needs a major effort. And, may be more important: Consistency between these artefacts has to be checked manually: a nightmare. Now, in the last timeframe, I did some research and I think that there are much better ways: Something as "automation". What I understand with "automation" is: Store all the information in xml-files and based on that create your documentation: html, xls, pdf,.... The transformation is done by using xsl. My questions are: 1. Can somebody give me hints how to tackle my needs most efficiently? 2. What is the best way to create html-pages which contain only static content (no user interaction, e.g. test-results) 3. Is xsl-transformation the right approach. 4. ...and more... I guess I have forgotten a lot of important questions Thank you for your tips in advance
modified on Wednesday, September 3, 2008 4:05 AM
-
Dear members, I have some beginners questions. I'm acting as a SW-architect and I have to create a lot of documentation. I do this with a lot of heterogenous tools: MS-Word, xls, Powerpoint, PDF, HTML, .... Everything is incompatible and needs a major effort. And, may be more important: Consistency between these artefacts has to be checked manually: a nightmare. Now, in the last timeframe, I did some research and I think that there are much better ways: Something as "automation". What I understand with "automation" is: Store all the information in xml-files and based on that create your documentation: html, xls, pdf,.... The transformation is done by using xsl. My questions are: 1. Can somebody give me hints how to tackle my needs most efficiently? 2. What is the best way to create html-pages which contain only static content (no user interaction, e.g. test-results) 3. Is xsl-transformation the right approach. 4. ...and more... I guess I have forgotten a lot of important questions Thank you for your tips in advance
modified on Wednesday, September 3, 2008 4:05 AM
Last time I checked, Software Architect is not a job for a beginner... That's why people start as Junior Developers and walk the line to higher positions. Along the way the Junior Developer would learn the best ways to design the solutions for any problem, and how to document the whole problem/process/solution most effectively. Don't get me wrong, I'm not trying to be mean, jerk or anything else... just make sure you're up for the responsibilities you're overtaking. On topic: I presume you need a way to document customer requirements, SW architecture, (detail) design, that sort of things, right? Try SparxSystems' Enterprise Architect. I believe it'll have all the features you'd need.
To hell with circumstances; I create opportunities.
-
Last time I checked, Software Architect is not a job for a beginner... That's why people start as Junior Developers and walk the line to higher positions. Along the way the Junior Developer would learn the best ways to design the solutions for any problem, and how to document the whole problem/process/solution most effectively. Don't get me wrong, I'm not trying to be mean, jerk or anything else... just make sure you're up for the responsibilities you're overtaking. On topic: I presume you need a way to document customer requirements, SW architecture, (detail) design, that sort of things, right? Try SparxSystems' Enterprise Architect. I believe it'll have all the features you'd need.
To hell with circumstances; I create opportunities.
Thanks for your reply. I already use EnterpriseArchitect for my personal needs. But there are 2 counter-indicators against Enterprise Architect 1. It cannot be introduced into the enterprise, because e.g. design, requirement, tracking-tools are already defined and extensively used 2. Enterprise Architect is capable only for small subsets of my tasks; e.g. I have "unit-test-reports" (based on xml) which have to be published, I have meeting-minutes, build-results, and much much more. A lot of my artefacts is the result of a continuous integration process Kind regards
-
Dear members, I have some beginners questions. I'm acting as a SW-architect and I have to create a lot of documentation. I do this with a lot of heterogenous tools: MS-Word, xls, Powerpoint, PDF, HTML, .... Everything is incompatible and needs a major effort. And, may be more important: Consistency between these artefacts has to be checked manually: a nightmare. Now, in the last timeframe, I did some research and I think that there are much better ways: Something as "automation". What I understand with "automation" is: Store all the information in xml-files and based on that create your documentation: html, xls, pdf,.... The transformation is done by using xsl. My questions are: 1. Can somebody give me hints how to tackle my needs most efficiently? 2. What is the best way to create html-pages which contain only static content (no user interaction, e.g. test-results) 3. Is xsl-transformation the right approach. 4. ...and more... I guess I have forgotten a lot of important questions Thank you for your tips in advance
modified on Wednesday, September 3, 2008 4:05 AM
Okay, if you're only a 'beginner' can you tell us which moron put you in charge of a project? The point being is that if you're accomplished and experienced enough to do the job you'd pretty much know the answers to the questions as, over the time you've been working your way up to this job, you'll have tried and tested most of the tools you'll end up using or be smart enough to figure out which tools are the most appropriate for the job at hand. You remind me the old business saying: "Would you really put a 20 year old in charge of the marketing budget?" Nevertheles I wish you luck and hope you can quickly grow into the job: however you got there it's a great opportunity - don't waste it.
-
Thanks for your reply. I already use EnterpriseArchitect for my personal needs. But there are 2 counter-indicators against Enterprise Architect 1. It cannot be introduced into the enterprise, because e.g. design, requirement, tracking-tools are already defined and extensively used 2. Enterprise Architect is capable only for small subsets of my tasks; e.g. I have "unit-test-reports" (based on xml) which have to be published, I have meeting-minutes, build-results, and much much more. A lot of my artefacts is the result of a continuous integration process Kind regards
Tomerland wrote:
I have meeting-minutes, build-results, and much much more.
This sorta sounds like a blog, which you are continuously updating. You could use tags for the different types of info.
Best wishes, Hans
[CodeProject Forum Guidelines] [How To Ask A Question] [My Articles]
-
Tomerland wrote:
I have meeting-minutes, build-results, and much much more.
This sorta sounds like a blog, which you are continuously updating. You could use tags for the different types of info.
Best wishes, Hans
[CodeProject Forum Guidelines] [How To Ask A Question] [My Articles]
-
I'm sure if you google for "enterprise blogs" or "intranet blogs" you'll get plenty of hits. And no, I have not set one up. The nice thing about blogs is that you can present the info you have, and then people in the company can comment on it, or update it, without being able to change your initial post. Also, it serves as a time machine, recording what decisions were made and why. Let us know if you set one up and how it goes.
Best wishes, Hans
[CodeProject Forum Guidelines] [How To Ask A Question] [My Articles]
-
Dear members, I have some beginners questions. I'm acting as a SW-architect and I have to create a lot of documentation. I do this with a lot of heterogenous tools: MS-Word, xls, Powerpoint, PDF, HTML, .... Everything is incompatible and needs a major effort. And, may be more important: Consistency between these artefacts has to be checked manually: a nightmare. Now, in the last timeframe, I did some research and I think that there are much better ways: Something as "automation". What I understand with "automation" is: Store all the information in xml-files and based on that create your documentation: html, xls, pdf,.... The transformation is done by using xsl. My questions are: 1. Can somebody give me hints how to tackle my needs most efficiently? 2. What is the best way to create html-pages which contain only static content (no user interaction, e.g. test-results) 3. Is xsl-transformation the right approach. 4. ...and more... I guess I have forgotten a lot of important questions Thank you for your tips in advance
modified on Wednesday, September 3, 2008 4:05 AM
I fully agree with the first reply, and want to add the following: Your idea of "automation" is a good idea, but your priorities are wrong. For docs, the most important thing is: writing it and maintaining it. Your process should be all around making it quick and easy to write, to keep it current, and to find. This should determine what tools you use - not the publishing process that connects these three. The "publishing process" of course should be automatic and fast, but if someone makes a chance and thinks "firing up the doc editor takes too long - I'll change that later", you have lost. 15 seconds can be "too long" already. Further, I yet have to find the tool chain that allows what you describe: a comfortable editor that outputs XML, for which you can download XSLT's to transform it into PDF. Maybe that tool is out there somewhere, for that's what the angle bracket fetishists XML guys say is the future.
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighist