Category项目工程

Confluence创建自定义宏

因为文档编辑需要,自己学着创建了一个Confluence自定义宏,大体情况是这样的,编写api文档的时候总要编辑url的地址,但是考虑到后期如果有服务器域名变更等的问题,可能就需要把所有文档里的接口地址都修改一遍,这样的操作想想都头皮发麻,于是想到了用宏来管理api的url链接。

首先我们分析下,url分为3个部分,域名(ip),端口,接口路径,所以我们需要的这个宏有对应的三个参数,其中域名部分因为不会变更,或者说需要变更的时候都要统一变更,所以这个部分可以做成一个selector。在简单的研习过Confluence的宏编写文档之后,于是写出了这个宏,代码如下

## Macro title: My Macro
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: CheungQ
## Date created: dd/mm/yyyy
## Installed by: CheungQ

## This is an example macro
## @param Host:title=域名|type=enum|enumValues=www.mydomain.com|required=true|desc=域名
## @param Port:title=端口|type=string|required=true|desc=端口号|default=80
## @param Name:title=API|type=string|required=true|desc=API路径,不用带斜杠

<a target="_blank" href="http://$paramHost:$paramPort/$paramName">http://$paramHost:$paramPort/$paramName</a>

 

接下来还是看这个宏的效果吧

 

另外付下官方文档中的相关参数说明

 

The sections below describe each of the attributes in detail.

Attribute name

Description

Required / Recommended / Optional

(an unnamed, first attribute) A unique name for the parameter. The parameter name is the first attribute in the list. The name attribute itself does not have a name. See the section on name below. Required
multiple Specifies whether the parameter accepts multiple values. Defaults to false. Optional
required Specifies whether the user must enter information for this parameter. Defaults to false. Optional
default The default value for the parameter. Optional
type The field type for the parameter. See the section on type below. Recommended
desc The parameter description will appear in the macro browser. Optional
title The parameter title will appear in the macro browser. If you do not specify a title, Confluence will use the parameter name. Recommended

 

 

Parameter type

The field type for the parameter. If you do not specify a type, the default is string.

Parameter type

Description

boolean Displays a checkbox to the user and passes the value ‘true’ or ‘false’ to the macro as a string.
enum Offers a list of values for selection. You can specify the values to appear in a dropdown in the macro browser. Example of specifying the enum values:

## @param colour:title=Colour|type=enum|enumValues=Grey,Red,Yellow,Green

Note about i18n: Confluence does not support internationalisation of the enum values.The value the user sees is the one passed to the macro as the parameter value, with the capitalisation given. In this case ‘Grey’, ‘Red’, etc.

string A text field. This is the default type. Example with a required field:

## @param status:title=Status|type=string|required=true|desc=Status to display
confluence-content Offers a control allowing the user to search for a page or blog post. Example:

## @param page:title=Page|type=confluence-content|required=true|desc=Select a page do use
username Search for user.

## @param user:title=Username|type=username|desc=Select username to display
spacekey Offers a list of spaces for selection. Passes the space key to the macro. Example:

## @param space:title=Space|type=spacekey
date Confluence accepts this type, but currently treats it in the same way as ‘string’. Example:

## @param fromDate:title=From Date|type=date|desc=Date to start from. Format: dd/mm/YYYY 

Note about dates: A user can enter a date in any format, you should validate the date format in your user macro.

int Confluence accepts this type, but treats it in the same way as ‘string’. Example with a default value:

## @param numPosts:title=Number of Posts|type=int|default=15|desc=Number of posts to display
percentage Confluence accepts this type, but treats it in the same way as ‘string’. Example:

## @param pcent:title=Percentage|type=percentage|desc=Number of posts to display 

为了项目上线而加班,真有必要吗?

大家都知道:软件项目的加班可能真是有百害而无一利,但总还有些时候,有些人有侥幸心理,或是现实情况实在无法让步,比如项目必须在某个日期上线; 在这些情况下,应该跟团队沟通些什么?Quora资深软件工程师Edmond Lau在自己的一篇博客中,给出了自己的看法。这篇博客名为《为了满足项目上线日期要求,我该怎么告诉我的团队工作更多时间?》。

文章一开始,Edmond指出:

在试图告诉团队要加班之前,一定要确保一点:为了保证上线日期,你有一个切实可行的计划。否则,从长远来看的最佳策略是:根据团队当前开发能力和效率,重新定义要上线的功能;或者将截止日期重新调整为更现实的时间。

接下来,Edmond列举了自己的亲身经验。他曾参与过两个持续多月大型项目,而且团队成员都是高手,专注投入在这两个项目上。为了在某个日期之前上线,工程经理要求团队加班工作,每周60到70个小时。可是项目最后还是没有按时完成。Edmond这样回顾项目的后果:

这样的方式让一些团队成员筋疲力尽,有些人后来离开了,其他人用了很久才恢复过来。这两个项目的情况都无法判断:加班是否真能加快进度,加班的决策在当时也许很合理,但是长远来看,两只团队都深受其害。我们从这两个项目中学到惨痛的教训:不管你多么希望项目在某个日期前完成,都对它能否做到这一点毫无帮助。不要将积极思考与现实的乐观主义混为一谈。

Edmond列举了几个加班无助于项目尽快交付的原因:

  • 工作更多时间,每小时的效率将会降低。

如果你的团队已经习惯了每周40小时工作的生活节奏,而且一年来都是如此,那么很可能他们加班的效率会低于平常,甚至可能产生负面影响。疲累和睡眠减少会伤害认知功能,而且降低工作质量。

他还列举了150年以来的研究文献,证明这一点,而且有些文献甚至说明:如果加班过多,

有问题的工作累计带来的负面影响,会导致项目完成日期延迟,甚至比同样的团队按照每周40小时的工作节奏完成得还要晚。

  • 很可能你现在落后的时间进度比你以为的还要多。

在工程中,做出准确的项目估算非常难以做到。进度已经晚了,说明上个月的工作就估算得不够。所以,可能过去的工作估算少了,更有可能的是:整个项目都估算少了,包括剩下几个月的工作。

我们在项目开始时估算得要比项目结束时准确,因为开始时的工作重点放在可以深入理解的工作之上;到结束时,团队常常低估整合测试用去的时间> ,而且每个没有预料到的问题都会让进度延后一周甚至更多。这些效应叠加起来会产生更多延迟。

他引用了《人月神话》里面的话:

特别是没有为系统测试留出足够时间,这会带来灾难性后果。因为延迟是在项目日程结束时来临的,除非交付日期快到了,没人会意识到进度上的问题。

  • 额外的工作时间会让团队精疲力竭。

Edmond引用了《人件》中的一个症状:“undertime”,也就是说:跟随加班而来的,常常是员工为了要补偿生活方面的损失,而在工作中耗费时间去做与工作无关之事。

我们的经验指出:额外工作时间的积极影响被大大夸大了,而其负面影响却从未有人考量。负面影响可能十分严重:错误、倦怠、失误不断增多、补偿用的“undertime”等等。

  • 额外的工作时间会伤害团队士气。

在Edmond看来,加班之前,可能团队每个人都有自己的方式来完成每周40小时的工作,而且还能保证团队的凝聚力。一旦要加班,可能某些人就要多完成一些不能多加班的人要做的事情,这会影响彼此之间的关系,以前开心的团队,现在可能就不开心了。

  • 管理向截止日期的冲刺,需要耗费更多管理开销。

为了管理额外工作而举行更多站立会议和其他会议,这很常见,因为你希望团队要彼此沟通,保证每个人都在做正确的事情。然而,这种额外的沟通开销常常不会放在工作估算中。

  • 向截止日期的冲刺,会刺激产生更多技术债务。

Edmond认为:为了赶进度而加班,几乎不可避免地会令得团队找捷径。而且在面临更多项目压力的情况下,这些技术债务很可能越积越多,将来一定要付出更多成本偿还。

不过,总有些现实情况不可避免,真到那时候,Edmond建议在沟通时要强调一下因素。

  • 要理解为什么进度落了这么远,找出根本原因,还要与团队沟通。

没赶上进度,是因为人们偷懒,还是因为项目要比想象的复杂,要占用更多时间?如果不能理解根本原因,也就不能有信心同样的问题不会在未来几个月出现。

  • 向团队说明更可行的项目计划和时间进度,说明为什么要加班才能真正赶上上线日期,还要说明怎么做。

    仅仅告诉团队他们落后了还不够,如果不能得出更详细、更明确的计划达成目标,这就是一个警告信号,说明你比你以为的情况更落后。

  • 确保团队每个人都能理解、认同你的新进度安排。

    如果关键成员不相信你的时间表可行,那就得好好想想:你可能无法在新的指定日期前完成你想完成的工作。要是无法做到所有人都认可,那么可能只有某些人认同加班,除了团队中会有不公平的感觉之外,可能你还是无法达成最后完成日期。

  • 重点放在项目、团队或是组织的整体工作目标上,说明为什么按时上线如此重要。

    如果你无法把团队融合在一起,这就是另一个警讯:说明不是所有人都像你这么有动力去加班。

最后,Edmond指出:

如果,在接下来冲刺的两个月时间里,你发现实际进度比修正后的还要延迟,那就准备放弃这个冲刺吧。接受现实,知道你可能是在马拉松的半程发起了冲刺,而终点线比你想的要远得多。不再可能让团队更努力去解决问题了。减少损失,不妨想想怎么制订一个应急计划应对后续问题。

错过截止日期很糟糕,但要是错过了截止日期,而且让团队精疲力尽,而且没有应急计划,这就更糟糕了。

这篇博客来自Edmond在Quora上回答的一个问题,还有很多其他人对这个问题做出了自己的回答。

译文出处:InfoQ

本文转自OSChina

© 2018 CheungQ

Theme by Anders NorénUp ↑